Registry / auth-security / oidc-provider

oidc-provider

JSON →
library2.3.4jsnpmunverified

oidc-provider is a comprehensive OAuth 2.0 Authorization Server implementation that includes full support for OpenID Connect 1.0, designed for Node.js environments. Currently stable at version 9.8.2, the library maintains an active release cadence with frequent minor and patch updates, often incorporating new features and specification compliance. Its key differentiators include extensive OpenID Certification across various profiles (e.g., Basic, Implicit, Hybrid, FAPI 1.0/2.0, CIBA), a wide array of implemented OAuth 2.0 and OIDC specifications (PKCE, JAR, PAR, DPoP, MTLS, Device Flow, Dynamic Client Registration, Back-Channel/RP-Initiated Logout, Token Introspection/Revocation, Resource Indicators, JARM, CIMD), and a highly configurable architecture that allows for custom storage adapters and interaction flows. It provides the core OIDC server logic, leaving UI and storage implementation to the developer, offering flexibility but also requiring careful custom integration.

npm install oidc-provider
INSTALL
IMPORT
SIG · OIDC-PROVIDER
O
oidc-provider
auth-securityjavascriptv2.3.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Provider
import { Provider } from 'oidc-provider';
const Provider = require('oidc-provider');
oidc-provider v8+ is primarily an ESM-first module. While CJS compatibility might exist via `exports` map, direct ESM import is the recommended and best-supported approach for modern Node.js applications.
errors
import * as errors from 'oidc-provider/lib/helpers/errors';
import { AccessDenied } from 'oidc-provider/lib/helpers/errors';
Error classes like `AccessDenied` are available via the `errors` module. Import them as a namespace or individually based on need. The path `lib/helpers/errors` is the conventional way to access these.
Adapter Interface (example)
import { Adapter, AdapterFactory } from 'oidc-provider'; // for type definitions or factory
When creating a custom storage adapter, you'll implement the `Adapter` interface. The `AdapterFactory` can be used to wrap your adapter class, providing a consistent way to manage adapter instances.

This quickstart demonstrates the instantiation of a basic OIDC Provider with a minimal in-memory adapter and client configuration, emphasizing the critical need for a persistent storage adapter, custom interaction UI, and securely managed JWKS for any production deployment. It illustrates the core `Provider` class and essential configuration structure.

import { Provider } from 'oidc-provider'; import { strict as assert } from 'assert'; // Minimal in-memory adapter for quickstart (DO NOT USE IN PRODUCTION) // A real application requires a persistent storage solution (e.g., database). class MemoryAdapter { constructor(name) { this.name = name; this.store = new Map(); } async upsert(id, payload, expiresIn) { this.store.set(id, { payload, expiresAt: Date.now() + (expiresIn * 1000) }); return id; } async find(id) { const record = this.store.get(id); return record && record.expiresAt > Date.now() ? record.payload : undefined; } async findByUser(userCode) { for (const [id, record] of this.store) { if (record.payload?.userCode === userCode) return this.find(id); } return undefined; } async findByUid(uid) { for (const [id, record] of this.store) { if (record.payload?.uid === uid) return this.find(id); } return undefined; } async destroy(id) { this.store.delete(id); } async consume(id) { const record = await this.find(id); if (record) { record.consumed = Date.now(); } return record; } } // Basic configuration (replace with your secure, production-ready config) const configuration = { clients: [{ client_id: 'test_client', client_secret: 'test_secret', redirect_uris: ['http://localhost:3000/cb'], response_types: ['code'], grant_types: ['authorization_code', 'refresh_token'], }], features: { // Enable PKCE and Refresh Tokens for better security and UX pkce: { enabled: true }, refreshToken: { enabled: true }, }, // You MUST provide your own interaction UI for login/consent/etc. // This function maps an interaction request to a URL for your UI. interactions: { url: (ctx, interaction) => { // In a real app, this would redirect to your custom login/consent page return `/interaction/${interaction.uid}`; }, }, adapter: MemoryAdapter, // Use the in-memory adapter for quick testing // For production, always generate and securely manage strong, rotated secret keys jwks: { keys: [{ "d": "f81f-example-private-key-part-DO-NOT-USE-IN-PROD", "dp": "f81f-example-private-key-part-DO-NOT-USE-IN-PROD", "dq": "f81f-example-private-key-part-DO-NOT-USE-IN-PROD", "ext": true, "kty": "RSA", "n": "f81f-example-public-key-part", "p": "f81f-example-private-key-part-DO-NOT-USE-IN-PROD", "q": "f81f-example-private-key-part-DO-NOT-USE-IN-PROD", "qi": "f81f-example-private-key-part-DO-NOT-USE-IN-PROD", "use": "sig" }] } }; const provider = new Provider('http://localhost:3000', configuration); // Example of how you would integrate with an HTTP server, e.g., Express: // import express from 'express'; // const app = express(); // app.use(provider.callback()); // app.listen(3000, () => console.log('OIDC Provider listening on port 3000')); console.log('OIDC Provider instantiated. Remember to set up a real adapter, interaction UI, and secure JWKS.'); // To make this code runnable for checklist.day validation: assert.ok(provider instanceof Provider, 'Provider was not instantiated correctly'); console.log('Quickstart complete: Provider instantiated successfully.');
Debug
Known issues
breakingVersion 8.0.0 introduced significant breaking changes including a shift to ESM-only module distribution, requiring Node.js >= 16, and substantial modifications to the Adapter interface and middleware setup. Direct `require()` statements for the main module may no longer work as expected.
fix
Migrate your project to use ES Modules (`import`/`export`), ensure Node.js >= 16, and update your custom Adapter implementations to conform to the new interface. Refer to the v8 migration guide for detailed instructions.
affects: >=8.0.0
breakingVersion 9.0.0 introduced further breaking changes, primarily impacting the `features` and `claims` configuration options, and making additional adjustments to the Adapter interface. Some previously deprecated options were also removed.
fix
Review your `Provider` configuration, especially the `features` and `claims` properties, and update your custom Adapter implementation methods if necessary. Consult the v9 changelog for specific changes.
affects: >=9.0.0
gotchaExperimental features in `oidc-provider` are explicitly noted as being subject to breaking changes in MINOR library versions. Relying on these features with a `^` (caret) dependency range in `package.json` can lead to unexpected breakages upon minor updates.
fix
When using experimental features, consider pinning `oidc-provider` with a `~` (tilde) operator (e.g., `"oidc-provider": "~9.7.0"`) in your `package.json` to avoid unexpected breaking changes, or carefully review changelogs for minor version updates that affect experimental features.
affects: >=7.x
gotchaoidc-provider requires developers to implement their own storage adapter for persistence and their own user interaction UI (login/consent pages). Failing to provide robust implementations for these can lead to critical security vulnerabilities or functional issues.
fix
Implement a secure, persistent storage adapter (e.g., for PostgreSQL, MongoDB, Redis) and a fully functional user interaction UI that handles login, consent, and other OIDC flows. The provided in-memory adapter is strictly for development and cannot be used in production.
affects: All
gotchaThe `jwks` configuration for provider keys is critical for cryptographic operations. Using insecure, hardcoded, or improperly managed keys, or failing to rotate them, is a major security risk. The `d` parameters for JWKS private keys must be kept absolutely secure.
fix
Generate strong, unique JWKS keys for each environment. Never hardcode private keys in source code for production. Implement a robust key management strategy using a Key Management System (KMS) or secure secret management service for storage and rotation.
affects: All
gotchaWhile `oidc-provider` supports Node.js 16+, certain features and internal dependencies (like `undici` for `fetch`) may require Node.js 18+ to function without additional polyfills or configuration.
fix
It is highly recommended to run `oidc-provider` on Node.js 18 or newer to ensure full compatibility, optimal performance, and to avoid potential issues related to missing native `fetch` or other web platform APIs.
affects: <18.0.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module ... Not supported by require().
Attempting to use `require()` to import `oidc-provider` or its submodules in a CommonJS context, but the library is distributed as ES Modules.
fix
Ensure your project is configured for ES Modules by setting `"type": "module"` in `package.json` or by using `.mjs` file extensions, and update `require()` calls to `import` statements.
Error: adapter for '...' not found
The `oidc-provider` instance could not find a registered adapter for a specific model (e.g., 'Session', 'AccessToken'). This usually means your custom adapter is missing required methods or is not correctly implemented/registered.
fix
Verify that your custom adapter class implements all required methods for the `Adapter` interface (check the `oidc-provider` documentation for the current interface) and that it is correctly passed in the `adapter` configuration option of the `Provider` constructor.
TypeError: interaction.uid is not a function (or similar interaction URL error)
The `interactions.url` configuration expects a function that returns a URL string for the interaction page, but it might be misconfigured, or the `interaction` object's properties are being accessed incorrectly.
fix
Ensure your `interactions.url` function correctly accepts `ctx` and `interaction` arguments and returns a valid string URL. The `interaction` object contains properties like `uid` (a string) and not a function. Check the documentation for the `Interaction` object structure.
TypeError: Cannot read properties of undefined (reading 'callback') when mounting middleware
This often happens when attempting to mount `provider.callback()` to an HTTP server middleware without `oidc-provider` being properly instantiated or configured, or if `provider.callback()` is being called incorrectly.
fix
Ensure `new Provider(...)` is called with valid arguments before accessing `provider.callback()`. The `provider.callback()` method should be correctly invoked as a middleware function (e.g., `app.use(provider.callback());` with Express/Koa).
Error: Invalid JWS signature
This error typically occurs during client authentication or token validation when a JWT (like a client assertion) is signed with an incorrect key, or the JWKS provided by the client (or in the provider's configuration) does not contain the correct public key for verification.
fix
Verify that the client's `jwks` (or `jwks_uri`) configuration is correct and up-to-date. Ensure the signing key used by the client for JWTs matches a public key available to the `oidc-provider` for verification. Check for clock skew between systems if `iat`/`exp` claims are involved.
Upgrade
Version history
2.3.4latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
16 hits · last 30 days
node
14
OpenAI (training)
1
Resources