Required dependencies

npm install jwt-decode

No native build steps, no pod install, no Android linking. The library targets browser globals (window, localStorage, indexedDB). For Node.js/SSR use InMemoryWebStorage as the state store and mock or polyfill crypto (Node 18+ has globalThis.crypto built-in).

Project setup

1. Copy the source/ directory into your project, e.g. src/oidc-client-ts/.
2. Ensure tsconfig.json targets at least "lib": ["ES2020", "DOM", "DOM.Iterable"] and "moduleResolution": "bundler" or "node16".

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "moduleResolution": "bundler",
    "strict": true
  }
}

3. Import from the barrel:

import { UserManager, User, Log, Logger } from "./oidc-client-ts/index";

4. Set up your OIDC settings (see Public API). No environment variables are required by the library itself; pass all configuration at runtime.
5. For silent renew, host a silent_renew.html page on your origin that calls userManager.signinSilentCallback().
6. For popup/redirect callbacks, call userManager.signinRedirectCallback() or userManager.signinPopupCallback() on the redirect/popup page.

Public API

UserManager

import { UserManager } from "./oidc-client-ts/index";

const userManager = new UserManager({
  authority: "https://idp.example.com",
  client_id: "my-spa",
  redirect_uri: "https://app.example.com/callback",
  scope: "openid profile email",
  response_type: "code",
});

The primary entry point. Orchestrates sign-in (redirect, popup, silent), sign-out, token renewal, and session monitoring. Use one long-lived instance per application. All methods return Promises.

User

import { User } from "./oidc-client-ts/index";
import type { UserProfile } from "./oidc-client-ts/index";

const user: User | null = await userManager.getUser();
if (user && !user.expired) {
  const profile: UserProfile = user.profile;
  const token: string = user.access_token;
}

Holds the authenticated user's tokens (access_token, id_token, refresh_token), expiry, and decoded profile claims. Call user.expired to check token validity before API calls.

Log / Logger

import { Log, Logger } from "./oidc-client-ts/index";
import type { ILogger } from "./oidc-client-ts/index";

Log.setLogger(console);       // direct to browser console
Log.setLevel(Log.DEBUG);      // DEBUG | INFO | WARN | ERROR | NONE

Static logging facade. Wire it to any ILogger-compatible sink at application startup. Disable in production by setting Log.setLevel(Log.NONE).

WebStorageStateStore

import { WebStorageStateStore } from "./oidc-client-ts/index";

const store = new WebStorageStateStore({ store: window.sessionStorage });
const userManager = new UserManager({
  authority: "https://idp.example.com",
  client_id: "my-spa",
  redirect_uri: "https://app.example.com/callback",
  userStore: store,
});

Persists OIDC state and user objects in localStorage or sessionStorage. Pass window.sessionStorage for tab-scoped sessions. Use InMemoryWebStorage for unit tests.

Working examples

Scenario - Redirect sign-in and callback handling

Standard SPA flow: redirect the user to the identity provider and process the authorization code on return.

import { UserManager, Log } from "./oidc-client-ts/index";

Log.setLogger(console);
Log.setLevel(Log.INFO);

const mgr = new UserManager({
  authority: "https://idp.example.com",
  client_id: "spa-client",
  redirect_uri: `${window.location.origin}/callback`,
  scope: "openid profile email",
  response_type: "code",
});

// On login button click:
async function login(): Promise<void> {
  await mgr.signinRedirect({ state: { returnUrl: window.location.pathname } });
}

// On /callback page:
async function handleCallback(): Promise<void> {
  const user = await mgr.signinRedirectCallback();
  console.log("Signed in:", user.profile.sub);
  const returnUrl = (user.state as { returnUrl?: string })?.returnUrl ?? "/";
  window.location.replace(returnUrl);
}

Scenario - Silent token renewal

Renew the access token in the background using a hidden iframe, avoiding user-visible redirects.

import { UserManager } from "./oidc-client-ts/index";

const mgr = new UserManager({
  authority: "https://idp.example.com",
  client_id: "spa-client",
  redirect_uri: `${window.location.origin}/callback`,
  silent_redirect_uri: `${window.location.origin}/silent_renew.html`,
  automaticSilentRenew: true,
  scope: "openid profile email offline_access",
});

mgr.events.addAccessTokenExpiring(() => {
  console.log("Access token expiring, attempting silent renew...");
});

mgr.events.addSilentRenewError((err) => {
  console.error("Silent renew failed:", err);
});

// In silent_renew.html:
// import { UserManager } from "./oidc-client-ts/index";
// new UserManager({}).signinSilentCallback();

Scenario - Popup sign-in with event-driven user loaded callback

Open a popup for authentication without navigating the main window.

import { UserManager, User } from "./oidc-client-ts/index";
import type { UserLoadedCallback } from "./oidc-client-ts/index";

const mgr = new UserManager({
  authority: "https://idp.example.com",
  client_id: "spa-client",
  redirect_uri: `${window.location.origin}/callback`,
  popup_redirect_uri: `${window.location.origin}/popup_callback.html`,
  scope: "openid profile",
});

const onUserLoaded: UserLoadedCallback = (user: User) => {
  console.log("User loaded via popup:", user.profile.email);
};

mgr.events.addUserLoaded(onUserLoaded);

async function loginPopup(): Promise<void> {
  try {
    const user = await mgr.signinPopup();
    console.log("Popup sign-in complete:", user.profile.sub);
  } catch (err) {
    console.error("Popup sign-in failed:", err);
  }
}

// In popup_callback.html:
// new UserManager({}).signinPopupCallback();

File walkthrough

• errors/ - Typed error classes: ErrorResponse for OAuth error responses, ErrorTimeout for navigation timeouts, ErrorDPoPNonce for DPoP nonce mismatch recovery.
• navigators/ - Concrete navigator classes (RedirectNavigator, PopupNavigator, IFrameNavigator) and their shared interfaces; each navigator opens a window and returns the response URL.
• utils/ - Internal utilities: CryptoUtils for PKCE/DPoP key generation, JwtUtils for decode-only JWT parsing, Logger/Log for leveled logging, Timer for expiry countdowns, UrlUtils for query string handling.
• AccessTokenEvents.ts - Fires accessTokenExpiring and accessTokenExpired events based on a configurable expiry offset timer.
• AsyncStorage.ts - Minimal async storage interface compatible with React Native's AsyncStorage.
• CheckSessionIFrame.ts - Embeds the OP's check_session_iframe endpoint and polls for session changes.
• Claims.ts - TypeScript interfaces for OidcStandardClaims, IdTokenClaims, JwtClaims, and OidcAddressClaim.
• ClaimsService.ts - Merges userinfo endpoint claims into ID token claims respecting the filterProtocolClaims setting.
• DPoPStore.ts - Exports DPoPState for storing DPoP key pairs; delegates persistence to an injected store.
• InMemoryWebStorage.ts - In-memory Storage implementation for environments without localStorage.
• IndexedDbDPoPStore.ts - Stores DPoP key material in IndexedDB for persistence across page loads.
• JsonService.ts - Performs fetch calls to JSON endpoints with optional extra headers and DPoP proof injection.
• MetadataService.ts - Loads, caches, and merges OIDC discovery metadata from {authority}/.well-known/openid-configuration.
• OidcClient.ts - Core client logic: creates authorization requests, processes responses, handles refresh token grants.
• OidcClientSettings.ts - Defines OidcClientSettings interface and OidcClientSettingsStore which normalizes defaults.
• OidcMetadata.ts - TypeScript type covering every field of an OIDC discovery document.
• RefreshState.ts - Carries refresh token and related claims between token endpoint calls.
• ResponseValidator.ts - Validates state, nonce, iss, aud, iat, and azp in authorization and token responses.
• SessionMonitor.ts - Wires CheckSessionIFrame events to UserManager to detect OP-side session changes.
• SessionStatus.ts - Union type "changed" | "error" returned by session checks.
• SigninRequest.ts - Constructs the authorization URL including PKCE, nonce, and all extra parameters.
• SigninResponse.ts - Parses the authorization response URL or form post into a typed object.
• SigninState.ts - Serializable state saved to storage before redirect; restored on callback.
• SignoutRequest.ts - Builds the end-session request URL with id_token_hint and post_logout_redirect_uri.
• SignoutResponse.ts - Parses the post-logout redirect response.
• SilentRenewService.ts - Listens for accessTokenExpiring events and triggers iframe-based silent renew automatically.
• State.ts - Base class for SigninState; handles random id generation and JSON serialization.
• StateStore.ts - Interface (get, set, remove, getAllKeys) implemented by WebStorageStateStore and InMemoryWebStorage.
• TokenClient.ts - Calls the token endpoint for authorization-code exchange, refresh-token grants, ROPC, and token revocation.
• User.ts - Holds decoded tokens and profile; provides expired, expires_in, scopes helpers.
• UserInfoService.ts - Fetches the userinfo endpoint and returns claims as a plain object.
• UserManager.ts - High-level API; delegates to OidcClient, navigators, SilentRenewService, and SessionMonitor.
• UserManagerEvents.ts - Extends base events with user-lifecycle callbacks (userLoaded, userUnloaded, silentRenewError, etc.).
• UserManagerSettings.ts - Extends OidcClientSettings with popup/iframe timeouts, storage options, and renew configuration.
• Version.ts - Exports a Version string constant matching the npm package version.
• WebStorageStateStore.ts - StateStore backed by localStorage or sessionStorage with a configurable key prefix.
• index.ts - Barrel file; re-exports every public class, type, and constant.

Common pitfalls and fixes

• crypto not defined in Node.js < 18: Use Node 18+ or polyfill with import { webcrypto } from "crypto"; globalThis.crypto = webcrypto as Crypto; before importing the library.
• localStorage not available in SSR (Next.js, Nuxt): Pass userStore: new InMemoryWebStorage() in settings and guard navigator calls inside useEffect/onMounted.
• Popup blocked by browser: Browsers block window.open unless called synchronously in a user gesture handler. Call signinPopup() directly inside the click event, not after an await.
• Silent renew page on a different origin: silent_redirect_uri must be on the exact same origin as the app; cross-origin iframes cannot post the response message back.
• jwt-decode ESM/CJS mismatch: If your bundler reports a module resolution error for jwt-decode, ensure your tsconfig/bundler is configured for ESM ("moduleResolution": "bundler" or "node16").
• State not found on callback after hard refresh: If using sessionStorage as the state store, the state is lost on a new tab. Switch to localStorage or ensure the sign-in and callback happen in the same tab.

Vibe-coding prompt template

I have the source code of `user@example.com` located in `src/oidc-client-ts/`
and a usage guide in `USAGE.md`. Please integrate OIDC authentication into my
existing project step-by-step using only the real exports from
`src/oidc-client-ts/index.ts` as documented in USAGE.md.

My project is a [describe: React SPA / Next.js app / Express + frontend / etc.].
My identity provider is [Auth0 / Keycloak / Azure AD / etc.] at authority URL
[https://...].

Tasks:
1. Create a singleton `UserManager` instance with my authority, client_id, and
   redirect_uri. Use `WebStorageStateStore` with `localStorage`.
2. Add a `login()` function that calls `signinRedirect()`.
3. Add a `/callback` route/page that calls `signinRedirectCallback()` and
   redirects to the app root.
4. Add a `logout()` function that calls `signoutRedirect()`.
5. Add a `getAccessToken()` helper that calls `getUser()` and returns
   `user.access_token`, or `null` if the user is expired or missing.
6. Enable `automaticSilentRenew: true` and create the `silent_renew.html` file.
7. Wire `Log.setLogger(console)` and `Log.setLevel(Log.WARN)` at app startup.

Use TypeScript throughout. Import every symbol from `src/oidc-client-ts/index`.
Do not install the npm package `oidc-client-ts`; use only the local source.

License and credit

oidc-client-ts is licensed under the Apache License 2.0. See source/LICENSE if present, or review the full license at the upstream repository. This block packages user@example.com unmodified; original copyright belongs to Brock Allen, Dominick Baier, and the authts contributors.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.