Okta Auth JavaScript SDK

The token.getWithIDPPopup(options) method (web browser only, async) is a specialized version of the popup flow designed for deployments using External Identity Providers.

Why use this? Standard getWithPopup uses okta_post_message for communication. However, if an external IDP sets a strict Cross-Origin-Opener-Policy (COOP), the popup and main window become isolated, breaking window.postMessage communication. getWithIDPPopup uses a query response mode instead, making it resilient to strict COOP policies.

Tradeoffs & Requirements:

1. No direct communication: The popup cannot talk to the main window via postMessage.
2. Manual Redirect Handling: After authentication, the popup must redirect to a registered redirectUri on your origin. This route must call authClient.handleIDPPopupRedirect() to relay the OAuth2 response back to the main window.
3. User Experience: The flow may feel less seamless than a standard popup due to the redirect requirement.

const { promise, cancel } = authClient.token.getWithIDPPopup({
  redirectUri: 'http://localhost:8080/popup/callback',
});
const { tokens } = await promise;
authClient.tokenManager.setTokens(tokens);

As of auth-js@8.x, the IDX client uses Step Mode by default. This mode requires explicit remediation steps, making client behavior consistent but requiring more code to manage the flow.

Step Mode (Default)

In Step Mode, every call to idx.proceed must include either an actions or step property to name the remediation to run. The client will execute that specific remediation and return the response, but it will not automatically perform subsequent (recursive) remediations. You must manually call idx.proceed for each step.

Limitations of Step Mode:

• No recursive remediation (automatic calls).
• flow is not supported.
• Up-front approach is not supported.

Legacy Mode (Deprecated)

Legacy Mode preserves pre-8.x behavior and is on a deprecation path. It supports recursive remediation, flow, and the Up-front approach. Use it only as a temporary migration aid.

Legacy Mode can be enabled during OktaAuth construction or on a per-call basis.

// Enable Legacy Mode globally during construction
const oktaAuth = new OktaAuth({
  ...config,
  idx: { enableLegacyMode: true }
});

// OR enable Legacy Mode for a specific call
const response = await idx.proceed({
  username: 'foo@bar.com',
  enableLegacyMode: true
});

A flow is a sequence of remediations used to bootstrap an IDX transaction to a specific user experience (e.g., unlock-account, register, recoverPassword).

Note: As of auth-js@8.x, the flow feature is not supported in the default IDX client. Instead of using the flow property, you should call idx.proceed({ step: '...' }) to drive the client into the desired state. To use the old flow behavior, you must enable Legacy Mode.

Flow Entrypoints

The flow is automatically set when calling these methods:

• idx.authenticate (sets flow to default)
• idx.register (sets flow to register)
• idx.recoverPassword (sets flow to recoverPassword)
• idx.unlockAccount (sets flow to unlockAccount)

Managing Flows

You can manually set or retrieve the current flow using:

• idx.getFlow(): Returns the current FlowIdentifier.
• idx.setFlow(flow): Manually sets the flow.
• idx.startTransaction({ flow: '...' }): Starts a transaction with a specific flow identifier.

// Starting a flow via entrypoint
await authClient.idx.recoverPassword();
const flow = authClient.idx.getFlow(); // "recoverPassword"

// Starting a flow via startTransaction
await authClient.idx.startTransaction({ flow: 'recoverPassword' });

The SDK supports several flows depending on your client type:

1. PKCE OAuth 2.0 flow (Recommended for SPAs): This is the default. It is secure for browser and NodeJS applications. It requires crypto.subtle and TextEncoder support.
2. Authorization Code flow (For Web/Native clients): Use this if you have a client secret stored securely. Set responseType: 'code' and pkce: false.
3. Implicit OAuth 2.0 flow (Discouraged): Use only if PKCE cannot be supported. Set pkce: false to enable. This is less secure as raw tokens are exposed in browser history.

// Example: Authorization Code flow
var config = {
  issuer: 'https://{yourOktaDomain}/oauth2/default',
  clientId: 'GHtf9iJdr60A9IYrR0jw',
  redirectUri: 'https://acme.com/oauth2/callback/home',
  responseType: 'code',
  pkce: false
};

// Example: Implicit flow
var config = {
  pkce: false,
  issuer: 'https://{yourOktaDomain}/oauth2/default',
};

The services configuration manages background tasks that improve user experience and security. These require OktaAuth to be running as a service.

• autoRenew: When true, the library attempts to renew tokens before they expire.
  • Active strategy: Background network requests refresh tokens seamlessly.
  • Passive strategy: Refresh attempts only occur when oktaAuth.isAuthenticated is called.
• syncStorage: Automatically syncs tokens across browser tabs using BroadcastChannel, IndexedDB, or localStorage. This prevents multiple tabs from sending simultaneous refresh requests.
• renewOnTabActivation: When enabled (requires autoRenew: true), the SDK uses the Page Visibility API to attempt a token renewal when a tab becomes active after an inactivity period defined by tabInactivityDuration (default 1800s).

// Example service configuration
services: {
  autoRenew: true,
  autoRemove: true,
  syncStorage: true,
  renewOnTabActivation: true,
  tabInactivityDuration: 1800 // seconds
}

Most IDX methods resolve an IdxTransaction object. Understanding these fields is critical for driving the flow.

status (IdxStatus)

• IdxStatus.SUCCESS: Flow ended successfully; tokens are available.
• IdxStatus.PENDING: Flow in progress; check nextStep to proceed.
• IdxStatus.FAILURE: SDK-level error; check error field.
• IdxStatus.TERMINAL: Flow reached a terminal state; check messages.
• IdxStatus.CANCELED: Flow was canceled (usually via idx.cancel()).

nextStep (Available in PENDING status)

Contains instructions for the next interaction:

• name: Identifier of the next step.
• type: Type of the authenticator.
• authenticator: The authenticator object.
• canSkip: Boolean indicating if the step is skippable.
• inputs: Array of required parameters (e.g., [{ name: 'username', label: 'Username' }]).
• poll: Polling configuration (if applicable).

Other Fields

• tokens: Available on SUCCESS. Contains session tokens.
• messages: Contains Form message or Terminal message from the engine.
• error: Available on FAILURE.
• meta: Available on startTransaction; contains PKCE meta, interactionHandle, etc.
• enabledFeatures: Available on startTransaction; lists features allowed by policy.
• availableSteps: Available on startTransaction; lists possible next steps.