electron-auth-session

Native OS authentication sessions for Electron apps. Opens the system browser in a secure, isolated session and intercepts the callback via a custom URL scheme.

• macOS: uses ASWebAuthenticationSession (10.15+)
• Windows: uses WebAuthenticationBroker (8+)
• Linux: not supported (isAvailable() returns false)

Installation

npm install electron-auth-session

After installing, rebuild the native module against Electron's Node.js ABI:

npx @electron/rebuild

Usage

import { AuthSession, UserCancelledError } from 'electron-auth-session';

if (!AuthSession.isAvailable()) {
  throw new Error('Native auth sessions are not supported on this platform');
}

const session = new AuthSession({
  url: 'https://example.com/auth?...',
  callbackScheme: 'myapp',
  windowHandle: browserWindow.getNativeWindowHandle(),
});

try {
  const callbackUrl = await session.start();
  // callbackUrl is e.g. "myapp://callback?..."
} catch (err) {
  if (err instanceof UserCancelledError) {
    // user closed the browser window
  } else {
    throw err;
  }
}

API

AuthSession.isAvailable()

Returns true if native auth sessions are supported on the current platform. Always safe to call — returns false instead of throwing if the native binary is missing.

new AuthSession(options)

Creates a session. Does not open the browser until start() is called.

| Option | Type | Description | | ---------------- | ------------------------ | -------------------------------------------------------------------- | | url | string | The URL to open in the browser session. | | callbackScheme | string | The URL scheme to intercept (e.g. "myapp" for myapp://callback). | | windowHandle | Buffer | Native window handle from BrowserWindow.getNativeWindowHandle(). | | headers | Record<string, string> | Extra HTTP headers (macOS 14.4+ only, ignored elsewhere). |

session.start()

Opens the browser and returns a Promise<string> that resolves with the full callback URL (e.g. myapp://callback?...) once the session completes.

Throws UserCancelledError if the user dismisses the session. Re-throws any other error unchanged.

session.cancel()

Cancels an in-progress session. No-op if no session is running.

UserCancelledError

Subclass of Error with name = "UserCancelledError". Thrown by start() when the user closes the browser before completing authentication.

Why not shell.openExternal?

shell.openExternal opens a tab in the user's default browser and relies on a custom URL scheme registered at the OS level to get the callback back into your app. That requires extra setup, leaves a tab open in the browser, and the session shares cookies and state with the rest of the browser.

ASWebAuthenticationSession and WebAuthenticationBroker open an ephemeral, sandboxed browser view managed by the OS. The session is isolated, the callback is intercepted at the OS level without any registered scheme, and the browser closes itself when done.

Supported Platforms

| Platform | Support | Minimum version | | -------- | ------- | --------------- | | macOS | Yes | 10.15 | | Windows | Yes | 8 | | Linux | No | - |