oidc-auth-client

OpenID Connect (OIDC) and OAuth 2.0 client library for JavaScript/TypeScript browser applications.

Handles authentication flows (redirect, popup, silent iframe), token lifecycle (storage, expiry, auto-renewal), session monitoring, and logout — against any standards-compliant OIDC provider (Keycloak, Auth0, Ory Hydra, Azure AD, etc.).

Installation

npm install oidc-auth-client

Quick Start

import { UserManager } from 'oidc-auth-client';

const userManager = new UserManager({
  authority: 'https://your-idp.com',
  client_id: 'your-client-id',
  redirect_uri: 'https://your-app.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Initiate login
await userManager.signinRedirect();

// Handle the callback page
const user = await userManager.signinRedirectCallback();
console.log(user.profile.sub);

// Get the current user
const current = await userManager.getUser();

// Sign out
await userManager.signoutRedirect();

TypeScript Usage

Types are generated from source — no separate @types package needed.

import {
  UserManager,
  UserManagerSettings,
  User,
  UserProfile,
} from 'oidc-auth-client';

const settings: UserManagerSettings = {
  authority: 'https://your-idp.com',
  client_id: 'your-client-id',
  redirect_uri: 'https://your-app.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
  automaticSilentRenew: true,
  silent_redirect_uri: 'https://your-app.com/silent-renew.html',
};

const userManager = new UserManager(settings);

userManager.events.addUserLoaded((user: User) => {
  console.log('User loaded:', user.profile.sub);
});

userManager.events.addAccessTokenExpired(() => {
  console.log('Token expired');
});

Subpath Imports

// Main entry — all public exports
import { UserManager, OidcClient } from 'oidc-auth-client';

// Auth only
import { UserManager } from 'oidc-auth-client/auth';

// Protocol utilities
import { TokenRevocationClient } from 'oidc-auth-client/protocol';

// Storage
import { WebStorageStateStore, InMemoryWebStorage } from 'oidc-auth-client/storage';

// Utilities
import { Log } from 'oidc-auth-client/utils';

Key Features

• Authorization Code + PKCE — secure default; hybrid flow not supported
• Silent Renew — automatic token refresh via hidden iframe
• Session Monitoring — OP check_session iframe integration
• Popup & Redirect — flexible authentication UX
• Cordova — mobile WebView support
• Web Crypto API — native browser crypto via jose; no polyfills
• TypeScript — source-level types; declarations auto-generated by tsc
• Tree-shakeable — sideEffects: false

Public API

// Auth
export { OidcClient, UserManager }
export type { CreateSigninRequestArgs, CreateSignoutRequestArgs, UserManagerSigninArgs }
export { OidcClientSettings, UserManagerSettings }
export type { OidcClientSettingsArgs, UserManagerSettingsArgs }
export { AccessTokenEvents, UserManagerEvents }
export { SessionMonitor, SilentRenewService, State, SigninState }
export type { StateArgs, SigninStateArgs }

// Models
export { User }
export type { UserData, UserProfile }

// Storage
export { WebStorageStateStore, InMemoryWebStorage }
export type { StateStore }

// Services
export { MetadataService }
export type { OidcMetadata }

// Navigation
export { CheckSessionIFrame, RedirectNavigator, PopupNavigator, IFrameNavigator }
export { CordovaPopupNavigator, CordovaIFrameNavigator }
export type { NavigateParams }

// Protocol
export { TokenRevocationClient }
export type { TokenSettings }

// Utils
export { Log, Global }

Project Structure

src/
├── auth/           # Authentication core
│   ├── Client.ts   # OidcClient + UserManager
│   ├── Settings.ts # OidcClientSettings + UserManagerSettings
│   ├── Events.ts   # AccessTokenEvents + UserManagerEvents
│   └── Session.ts  # State, SigninState, SessionMonitor, SilentRenewService
│
├── protocol/       # OIDC protocol
│   ├── Requests.ts          # SigninRequest + SignoutRequest
│   ├── Responses.ts         # SigninResponse + SignoutResponse + ErrorResponse
│   ├── ResponseValidator.ts # Token + claims validation
│   └── TokenService.ts      # TokenClient + TokenRevocationClient + UserInfoService
│
├── navigation/     # Browser navigation strategies
│   └── Navigator.ts # Redirect, Popup, IFrame, Cordova navigators
│
├── storage/        # Client-side persistence
│   └── Storage.ts  # WebStorageStateStore + InMemoryWebStorage
│
├── crypto/         # Cryptographic operations
│   └── Crypto.ts   # JoseUtil (jose-based) + generateRandom
│
├── services/       # Infrastructure
│   ├── Http.ts     # UrlUtility + JsonService + MetadataService
│   └── Timer.ts    # Timer + ClockService
│
├── models/         # Domain models
│   └── User.ts     # User
│
├── types/          # Shared contracts
│   ├── navigator.ts # NavigateParams, NavigatorResponse, INavigator
│   ├── crypto.ts    # JwtHeader, JwkKey, JwtPayload, ParsedJwt
│   ├── user.ts      # UserProfile
│   └── storage.ts   # StateStore
│
└── utils/          # Utilities
    ├── Log.ts      # Logging
    ├── Global.ts   # Global timer/interval access
    └── Event.ts    # EventCallback + EventEmitter

Examples

See docs/examples/ for working integrations:

Web

| Example | Description | |---------|-------------| | docs/examples/web/spa/ | Vanilla JS single-page app | | docs/examples/web/react/ | React with useAuth hook and context | | docs/examples/web/vue/ | Vue 3 with useAuth composable |

Guides

| Example | Description | |---------|-------------| | docs/examples/api/ | Authenticated API calls (fetch, axios) | | docs/examples/advanced/ | Popup, silent renew, multi-tab sync | | docs/examples/provider/ | Identity provider configurations | | docs/examples/security/ | Security best practices |

Scripts

| Script | Command | Purpose | |--------|---------|---------| | build | tsc | Compile TypeScript → dist/ | | type-check | tsc --noEmit | Type-check without emitting | | test | vitest | Watch mode | | test:run | vitest run | Run once (CI) | | test:coverage | vitest run --coverage | Coverage report | | test:package | node dist/index.js | Smoke-test compiled output |

# Run tests
npm run test:run        # 13 test files, 170 tests

# Build
npm run build           # compiles to dist/

# Type check
npm run type-check

Versioning

Version is managed entirely by the CI/CD pipeline from git tags. Do not edit version in package.json manually.

git tag v1.0.0
git push origin v1.0.0

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Copyright (c) Callis Ezenwaka. All rights reserved.