@axa-fr/oidc-client

A framework-independent OpenID Connect (OIDC) client for browser applications, written in TypeScript. It supports Authorization Code Flow with PKCE, session restoration, token renewal, multiple named configurations, optional service-worker token isolation, Pushed Authorization Requests (PAR), and DPoP.

For React applications, use @axa-fr/react-oidc.

• Quick start
• Service worker
• Configuration
• Token renewal
• Pushed Authorization Requests (PAR)
• DPoP
• API
• Errors and events
• Named configurations and routing
• Service-worker protocol
• Examples and further reading

Quick start

npm install @axa-fr/oidc-client

Register a public browser client with your identity provider:

1. Enable Authorization Code Flow with PKCE.
2. Register your application's exact callback URL, such as https://app.example.com/authentication/callback, and its post-logout URL.
3. Allow your application's origin to call the provider's browser-accessible endpoints through CORS.
4. Choose the scopes your application needs. Request offline_access only if your provider uses it to issue refresh tokens.

Never put a client secret in browser code. Replace the example issuer and client ID below with your own values. Configure your web server to serve the application on the callback route as well as /.

Add these elements to your page:

<p id="session-status" role="status">Loading session…</p>
<button id="login" type="button" hidden>Sign in</button>
<button id="logout" type="button" hidden>Sign out</button>

Run this module when those elements are available, including on the callback route:

import { OidcClient } from '@axa-fr/oidc-client';

const configuration = {
  client_id: 'your-public-client',
  authority: 'https://issuer.example.com',
  redirect_uri: `${window.location.origin}/authentication/callback`,
  scope: 'openid profile',
};

const oidcClient = OidcClient.getOrCreate(() => fetch)(configuration);
const status = document.getElementById('session-status');
const loginButton = document.getElementById('login');
const logoutButton = document.getElementById('logout');

function showError() {
  status.textContent = 'Authentication could not be completed. Please try again.';
}

loginButton.addEventListener('click', () => {
  oidcClient.loginAsync('/').catch(showError);
});
logoutButton.addEventListener('click', () => {
  oidcClient.logoutAsync('/').catch(showError);
});

async function start() {
  if (window.location.pathname === new URL(configuration.redirect_uri).pathname) {
    const { callbackPath } = await oidcClient.loginCallbackAsync();
    window.history.replaceState(null, '', callbackPath || '/');
  } else {
    await oidcClient.tryKeepExistingSessionAsync();
  }

  const isAuthenticated = oidcClient.tokens != null;
  status.textContent = isAuthenticated ? 'Signed in' : 'Not signed in';
  loginButton.hidden = isAuthenticated;
  logoutButton.hidden = !isAuthenticated;
}

start().catch(showError);

This minimal example uses browser storage, not a service worker. Read the next section before choosing a token-storage strategy for production.

Call a protected API

Use the client's fetch wrapper after authentication:

const oidcFetch = oidcClient.fetchWithTokens(fetch);
const response = await oidcFetch('https://api.example.com/profile');

if (!response.ok) {
  throw new Error(`API request failed with status ${response.status}`);
}
const profile = await response.json();

The wrapper attaches an access token, or a token placeholder when the service worker hides it, and integrates with token renewal. Only use it for API URLs you trust: the wrapper itself is not a destination allowlist. HTTP error responses still need an explicit response.ok check.

Service worker

The optional service worker can keep access and refresh tokens outside the application's JavaScript context and attach access tokens to configured API requests. It does not prevent XSS: injected code can still act through your application and make requests. Continue to use normal XSS defenses, carefully restrict trusted destinations, and avoid rendering or logging raw tokens.

sequenceDiagram
    participant App as Browser application
    participant IdP as Identity provider
    participant SW as OIDC service worker
    participant API as Trusted API
    App->>IdP: Authorization request with PKCE
    IdP-->>App: Redirect with authorization code
    App->>SW: Token request
    SW->>IdP: Exchange code and verifier
    IdP-->>SW: Tokens
    SW-->>App: Token placeholders and session information
    App->>SW: Protected API request
    SW->>API: Request with access token
    API-->>App: Response through service worker

The diagram shows worker mode with access-token hiding enabled. The ID token and decoded claims may still be available to application code.

Install and update the worker

node ./node_modules/@axa-fr/oidc-client/bin/copy-service-worker-files.mjs public

Replace public with your application's static-assets directory, and ensure that directory exists before running the command. This creates or updates OidcServiceWorker.js and creates OidcTrustedDomains.js if it does not already exist. Keep the worker version aligned with the client package; for example, merge this script into your package.json:

{
  "scripts": {
    "postinstall": "node ./node_modules/@axa-fr/oidc-client/bin/copy-service-worker-files.mjs public"
  }
}

Edit public/OidcTrustedDomains.js, not the generated worker:

const trustedDomains = {
  default: {
    oidcDomains: [/^https:\/\/issuer\.example\.com(?:\/|$)/],
    accessTokenDomains: [/^https:\/\/api\.example\.com\//],
  },
};

Include the provider's endpoint origins if they differ from its issuer URL. Keep access-token destinations as narrow as possible; patterns can include paths. String entries are interpreted as regular-expression prefixes, not exact origin matches. The example uses anchored regular expressions with escaped dots and hostname boundaries to avoid unintended matches. The default key must match the OIDC configuration name.

Add these options to your client configuration:

service_worker_relative_url: '/OidcServiceWorker.js',
service_worker_only: true,

Serve the worker from a URL whose scope covers your application, using HTTPS (or localhost for development). With service_worker_only: true, login requires an available service worker. With false (the default), the client can fall back to browser storage when worker mode is unavailable. Choose that fallback deliberately.

Trusted-domain options

These options belong in each named entry in OidcTrustedDomains.js, not in OidcConfiguration.

With allowMultiTabLogin: true, use oidcClient.fetchWithTokens(fetch) for protected API requests. Its tab-specific token placeholder tells the worker which session to use. Plain fetch or a default Axios request does not provide that marker, so automatic token attachment cannot select the tab's token and requests may receive HTTP 401. Use the OIDC fetch directly, or an integration that actually routes requests through it.

Configuration

The public OidcConfiguration type is the complete reference. Required fields are client_id, authority, redirect_uri, and scope.

Silent login

Silent login uses an iframe and the provider's existing session. It depends on provider support and browser cookie/privacy policies; it is not a guaranteed replacement for refresh tokens.

For a vanilla application, implement both the silent_login_uri page and the silent_redirect_uri callback page. The login page starts loginAsync with isSilentSignin: true (the third argument); the callback page calls silentLoginCallbackAsync(). Keep these routes separate from the interactive callback. The React provider handles these routes for you; its silent-login route implementation is also a reference for forwarding silent-login parameters.

Token renewal

By default, the client schedules renewal before tokens expire. It uses a refresh token when available, or the configured silent-login flow. Refresh-token issuance and lifetime remain provider decisions.

For renewal only when an API request needs it:

import { TokenAutomaticRenewMode } from '@axa-fr/oidc-client';

const renewalOptions = {
  token_automatic_renew_mode: TokenAutomaticRenewMode.AutomaticOnlyWhenFetchExecuted,
};

Merge this option into your configuration and use fetchWithTokens(fetch) or getValidTokenAsync() before protected requests. Plain fetch does not trigger this renewal mode.

• renewTokensAsync(extras?, scope?) requests renewal and preserves the non-throwing behavior for terminal OIDC failures.
• renewTokensOrThrowAsync(extras?, scope?) returns tokens or rejects, for callers that need explicit failure handling.
• Automatic renewal reports failures through events.

Pushed Authorization Requests (PAR)

PAR (RFC 9126) sends authorization parameters to the provider before navigating the browser.

If metadata says require_pushed_authorization_requests: true, 'auto' also fails when the endpoint is missing. Set par_request_timeout to adjust the default 10-second timeout.

Once PAR is selected, the client sends authorization parameters (including state, nonce, PKCE, and login extras) as application/x-www-form-urlencoded data. The subsequent browser redirect carries client_id and the returned request_uri. An endpoint failure or invalid response never silently downgrades to the front-channel flow.

Failures use PushedAuthorizationRequestError, with codes from PushedAuthorizationRequestErrorCode: ENDPOINT_UNAVAILABLE, REQUEST_FAILED, or INVALID_RESPONSE. Use isPushedAuthorizationRequestError(error) and inspect code, plus status, oauthError, and oauthErrorDescription when available.

The PAR endpoint must allow CORS from your application and accept public clients without a client secret. If discovery is unavailable, configure pushed_authorization_request_endpoint and, where applicable, require_pushed_authorization_requests in authority_configuration.

DPoP

Demonstrating Proof of Possession (RFC 9449) binds supported tokens to a key and uses signed proofs for requests. It requires support from the authorization server and resource server. It reduces the usefulness of a stolen token without its key; it does not make an application immune to XSS.

For client-side DPoP, set demonstrating_proof_of_possession: true in the OIDC configuration and opt in for protected requests:

const dpopFetch = oidcClient.fetchWithTokens(fetch, true);
const response = await dpopFetch('https://api.example.com/profile', { method: 'GET' });

Similarly, pass true as the second argument to userInfoAsync(false, true) if the user-info endpoint requires DPoP. For worker-side DPoP, configure demonstratingProofOfPossession in the matching trusted-domain entry and review demonstratingProofOfPossessionOnlyWhenDpopHeaderPresent.

The default cryptographic configuration uses ECDSA P-256, SHA-256, and the ES256 JWT algorithm. Override algorithms through demonstrating_proof_of_possession_configuration (client) or demonstratingProofOfPossessionConfiguration (worker). See DemonstratingProofOfPossessionConfiguration.

API

See OidcClient for full TypeScript signatures.

You can inject a custom location adapter as the second argument to getOrCreate, using the exported ILOidcLocation interface and OidcLocation implementation.

Errors and events

Known authentication, callback, renewal, and network failures use OidcError. Inspect stable code and phase fields rather than parsing messages. Other fields include retryable, optional status, oauthError, oauthErrorDescription, and cause.

import { OidcError, OidcErrorCode } from '@axa-fr/oidc-client';

try {
  await oidcClient.renewTokensOrThrowAsync();
} catch (error) {
  if (error instanceof OidcError && error.code === OidcErrorCode.LOGIN_REQUIRED) {
    await oidcClient.loginAsync('/');
  } else {
    throw error;
  }
}

retryable means a retry without user interaction may succeed, not that one is always performed automatically. Network failures, HTTP 408/429/5xx responses, and DPoP nonce challenges can be retryable; LOGIN_REQUIRED needs an interactive login.

Non-throwing flows also expose errors through events. Refresh event payloads include an error field; user-info, logout, and protected API requests have dedicated error events. Log only selected diagnostic fields, not complete event payloads:

const subscriptionId = oidcClient.subscribeEvents((name, data) => {
  const error = data instanceof OidcError ? data : data?.error;
  if (error instanceof OidcError) {
    console.warn(name, error.code, error.phase, error.status);
  }
});

// When the subscriber is no longer needed:
oidcClient.removeEventSubscription(subscriptionId);

Token synchronization events

Use OidcClient.eventNames with subscribeEvents to observe synchronization, including checks that reuse valid tokens without a refresh request. Automatic renewal checks can emit these events approximately once per second; browser scheduling and the time spent synchronizing can delay them.

One synchronization run emits a begin event followed by an end or error event. Internal refresh retries do not emit additional lifecycle pairs. When a cross-tab lock is needed but unavailable, syncTokensAsync_lock_not_available is emitted before synchronization begins and can repeat while waiting for the lock. The lifecycle events are emitted both with and without a lock.

An end event reports resolution, including the following outcomes:

Resolved failures such as 'SESSION_LOST' emit an end event rather than a synchronization error event. After an error event, the original synchronization exception is rethrown; no end event follows it.

These events cover synchronization itself. Initial worker setup and lock acquisition happen before the begin event; subsequent storage updates, session destruction, and timer scheduling happen after the end event. Failures in those steps are outside this event boundary, so an end event does not guarantee that the renewal call has finished successfully.

Keep subscribers lightweight and do not throw: subscriber exceptions propagate and can interrupt renewal. Log only selected diagnostic fields. The error payload contains the original exception, whose properties or cause may include sensitive data; do not log complete payloads, exceptions, or tokens.

import { isOidcError, OidcClient } from '@axa-fr/oidc-client';

// Use an already initialized client.
const oidcClient = OidcClient.getOrThrow();
const subscriptionId = oidcClient.subscribeEvents((name, data) => {
  if (name === OidcClient.eventNames.syncTokensAsync_end) {
    console.debug(name, data.status);
  } else if (name === OidcClient.eventNames.syncTokensAsync_error) {
    if (isOidcError(data.error)) {
      console.warn(name, data.error.code, data.error.phase, data.error.status);
    } else {
      console.warn(name);
    }
  }
});

// When the subscriber is no longer needed:
oidcClient.removeEventSubscription(subscriptionId);

React applications can observe the same payloads with the provider's onEvent(configurationName, eventName, data) callback. See React error handling for its session-loss response.

Missing or mismatched login state

OidcStateError extends OidcError and identifies callback-state failures:

• OidcStateErrorCode.STATE_MISSING: stored authorization state is missing.
• OidcStateErrorCode.STATE_MISMATCH: returned state does not match stored state.
• OidcStateErrorCode.NONCE_MISSING: stored nonce is missing.

Use isOidcStateError(error) and inspect error.code, especially for errors passed through silent-login handling. Storage clearing, eviction, and competing login attempts can cause these failures. Do not bypass state or nonce checks; offer a fresh login. During silent renewal, a missing nonce is reported through the session-lost flow.

Named configurations and routing

Use distinct names for separate providers or sessions with different scopes:

const paymentsClient = OidcClient.getOrCreate(() => fetch)(paymentsConfiguration, 'payments');
const existingClient = OidcClient.get('payments');

Each name reuses its initialized configuration. Give configurations distinct callback routes and matching keys in OidcTrustedDomains.js.

The library retains hash-route callback matching for legacy integrations. However, OAuth redirect URIs must not contain a fragment: use path-based callback URLs, as in the quick start, for new deployments. Existing hash-callback setups depend on provider-specific behavior and need matching application routing. Interactive and silent callback URLs must be different.

Service-worker protocol

The worker's versioned postMessage protocol is documented in PROTOCOL.md. Constants and helpers such as PROTOCOL_VERSION, ServiceWorkerMessageType, TOKEN_PLACEHOLDERS, and buildSecuredTokenPlaceholder are exported from @axa-fr/oidc-client and @axa-fr/oidc-client-service-worker/protocol.

import { OidcClient, ServiceWorkerMessageType } from '@axa-fr/oidc-client';

const client = OidcClient.getOrThrow();
const result = await client.signalServiceWorker<{ state: string }>({
  type: ServiceWorkerMessageType.GET_STATE,
  configurationName: 'default',
  data: null,
});

This requires an active worker. See the protocol reference for payloads, timeouts, and compatibility guarantees; avoid logging protocol responses containing session state.

Examples and further reading

• Vanilla JavaScript demo — complete application and local development instructions.
• React guide and React demo.
• FAQ and deployment guidance.
• Service-worker source and protocol.
• Service-worker package guide.

The demos belong to the pnpm monorepo. Follow their READMEs rather than installing each workspace independently.

For source development, use the root contributor commands and the committed lockfile. Keep this package's Vitest and coverage versions aligned.