openid-client

openid-client is a certified OAuth 2 and OpenID Connect relying-party library that simplifies integrating with authorization servers across JavaScript runtimes including Node.js, Deno, Bun, browsers, Cloudflare Workers, and Electron. It provides small, composable functions for the most common authentication and authorization flows — Authorization Code with PKCE, Refresh Token, Device Authorization, CIBA, and Client Credentials.

Built on the Web Crypto and Fetch APIs, it ships first-class support for advanced security profiles such as FAPI 1.0/2.0, DPoP, PAR, JAR, JARM, token introspection and revocation, dynamic client registration, and a ready-made Passport strategy, making it a dependable foundation for standards-compliant identity integrations.

What You Get

• Authorization Server Metadata discovery and issuer identification
• Authorization Code Flow with mandatory PKCE plus Refresh Token, Device Authorization, CIBA, and Client Credentials grants
• Advanced security extensions: DPoP, PAR, JAR, JARM, and FAPI 1.0/2.0 conformance
• Token introspection and revocation, UserInfo and protected-resource requests, and dynamic client registration
• A drop-in Passport strategy and universal runtime support (Node.js, Deno, Bun, browsers, Cloudflare Workers, Electron)

Common Use Cases

• Adding Sign in with an OpenID Provider (Auth0, Okta, Keycloak, Entra ID) to a web app
• Implementing the Device Authorization Grant for CLIs, TVs, and input-constrained devices
• Building FAPI-compliant clients for open banking and other high-assurance integrations

Under The Hood

Architecture

The library is organized as a flat set of exported functions in src/index.ts (~4,475 lines) rather than a class hierarchy. A Configuration object produced by discovery() holds server metadata and client credentials, and per-configuration internal state (auth method, DPoP/JARM/decrypt handlers, JWKS cache) is stashed in a module-level WeakMap (props) accessed via the int() helper, keeping private state off the public surface. Each flow — buildAuthorizationUrl, authorizationCodeGrant, initiateDeviceAuthorization/pollDeviceAuthorizationGrant, clientCredentialsGrant — delegates the underlying RFC-conformant HTTP and token-validation work to the oauth4webapi primitive layer, with openid-client providing the higher-level, ergonomic orchestration. A separate src/passport.ts (~732 lines) wraps these functions into a Passport Strategy.

Tech Stack

Written in TypeScript (94% of the codebase) and distributed as pure ESM (with require(esm) interop on modern Node). Runtime dependencies are minimal and sharply scoped: oauth4webapi for the low-level OAuth/OIDC protocol primitives and jose for JWE decryption. It relies on standard Web Platform globals (WebCryptoAPI, Fetch) rather than Node built-ins, which is what enables universal runtime support. Build is via esbuild/ts-blank-space; docs via TypeDoc.

Code Quality

The repository is mature and rigorously tested. Unit tests live in test/ (dcr, decryption, generic-grant, issuer-check, passport, retry-after, and regression tests for specific issues) using AVA, and an extensive end-to-end conformance harness in tap/ runs the same suite across Node.js, Deno, Bun, browsers, Cloudflare Workers, and Electron against a real oidc-provider. The author has formally certified the library against OpenID Connect Basic, FAPI 1.0, and FAPI 2.0 Relying Party conformance profiles, and a documented Security Policy is maintained.

API Design The public API favors small, explicit, single-purpose functions over a stateful client object, which keeps tree-shaking effective (sideEffects: false) and makes each flow readable. TypeScript types are thorough and the TypeDoc-generated reference plus a rich examples/ directory (oauth, oidc, dpop, jar, jarm, par, passport) mean common flows are copy-paste ready. The trade-off is that OAuth/OIDC domain knowledge is still required — the surface is broad because the protocol is — but naming is consistent and PKCE/state handling is guided by the docs.