oidc-provider

oidc-provider is a certified OAuth 2.0 and OpenID Connect authorization server implementation for Node.js. Rather than shipping as a hosted service, it is a library you mount directly into an existing Koa, Express, Fastify, or Hapi application, giving you full control over how authentication, client registration, and token issuance work inside your own infrastructure.

It implements a broad set of OAuth2/OIDC specifications out of the box, including PKCE, Dynamic Client Registration, the Device Authorization Grant, DPoP, mutual-TLS token binding, FAPI 1.0/2.0, CIBA, and Pushed Authorization Requests, and has been independently certified against several OpenID Connect conformance profiles. Storage is fully pluggable through an adapter interface, and the user-facing interaction flows for login, consent, and device verification are left for the implementing application to design, making it a foundation for a custom-built, self-hosted identity provider rather than a drop-in service.

What You Get

• A certified OAuth 2.0 / OpenID Connect authorization server implementation you mount into your own app instead of running as a separate hosted service.
• Broad protocol coverage — PKCE, Dynamic Client Registration, Device Flow, DPoP, mTLS, FAPI 1.0/2.0, CIBA, PAR, JAR, and JARM — enabled through configuration rather than custom code.
• A pluggable storage adapter interface so token, grant, and session persistence can be backed by any database, with an in-memory adapter provided for development.
• Full control over user-facing interaction flows (login, consent, device verification) via an interaction policy your application implements and renders.
• TypeScript type declarations and an extensively documented configuration surface covering claims, scopes, response types, and token formats.

Common Use Cases

• Standing up a self-hosted identity provider for a company’s own products instead of paying for a third-party auth platform.
• Adding OpenID Connect support to an existing Koa, Express, Fastify, or Hapi application without rearchitecting it.
• Building FAPI-conformant authorization servers for banking or open-finance integrations that require strict security profiles.
• Implementing device-flow or CIBA-based sign-in for CLIs, smart TVs, and other browserless clients.

Under The Hood

Architecture The Provider class in lib/provider.js directly subclasses Koa, owning the request-handling lifecycle rather than sitting beside it; internal state (keystore, models, adapter bindings) is held in a private weak-cache instance rather than public fields. Route handlers for each OAuth/OIDC endpoint live under lib/actions/ (authorization, grants, token, userinfo, introspection, revocation, discovery, end_session, registration, jwks, credential), and initialize_app.js wires these onto the Koa router at construction time. Persistence is delegated entirely to an adapter contract (lib/adapters/memory_adapter.js is the bundled default) that every model in lib/models/ depends on via shared base_model.js/base_token.js mixins, so swapping the adapter or the underlying Koa app touches the whole model layer. User-facing login/consent/device-verification flows are governed by a configurable state machine in lib/helpers/interaction_policy/, deliberately left for the host app to implement rather than hardcoded.

Tech Stack The runtime dependency list is intentionally small — koa (the app framework it subclasses), jose (JWT/JWK handling, from the same author), and debug for diagnostics — with persistence and UI left to the integrator. It ships as pure ESM ("type": "module") targeting current Node.js LTS releases, and lib/index.js actively detects and warns on unsupported runtimes (Deno, Bun, Cloudflare Workers). Development and test dependencies pull in Express, Fastify, Hapi, and Koa-specific packages purely to exercise cross-framework mounting scenarios, plus Mocha, Chai, Sinon, and fast-check for the test suite, and Biome for linting. No bundler or database driver is part of the core — the library is a mountable middleware layer, not a standalone server.

Code Quality The test/ directory holds 200+ spec files organized by feature (pkce, dpop, ciba, fapi, device_code, registration, and more), run through a custom harness (test/run.js) that spins up a real HTTP server and remounts the provider under bare, Express, Koa, Fastify, and Hapi configurations to verify framework-agnostic behavior, with fast-check adding property-based fuzzing on top of Mocha/Chai/Sinon. Errors are explicit and typed through a dedicated hierarchy in lib/helpers/errors.js (InvalidClient, SessionNotFound, OIDCProviderError, etc.) rather than generic Error throws. Linting runs via Biome with targeted rule overrides for the models directory, and CI is configured under .github/ to run the full suite on every change. Hand-maintained .d.ts declarations under types/ cover the public API even though the source itself is plain JavaScript.

What Makes It Unique Most Node.js OAuth libraries handle a narrow slice of the specification; oidc-provider implements an unusually wide surface, including several draft and emerging specs (FAPI 2.0, CIBA, DPoP, mutual-TLS binding, PAR, JAR, Rich Authorization Requests, and OpenID for Verifiable Credential Issuance) that have few or no other mature Node.js implementations, and it has pursued independent OpenID Certification against multiple conformance profiles — a costly distinction most auth libraries skip entirely. Combined with its adapter-based persistence contract and fully pluggable interaction policy, it functions less like a token-issuing middleware and more like a customizable authorization-server toolkit.