Copy source: Place the source/ directory into your project, e.g. src/oidc/.

Public API

Provider

import Provider from './src/oidc/index.js';

const provider = new Provider(issuer: string, configuration: Configuration): Provider;
// provider.callback() → http.RequestListener (attach to express/koa/http)
// provider.app        → underlying Koa application

The main class. Pass your issuer URL and a configuration object covering clients, jwks, adapter, features, ttl, scopes, claims, and interaction hooks. Mount provider.callback() on any Node.js HTTP framework.

errors

import { errors } from './src/oidc/index.js';

errors.InvalidClient       // extends OIDCProviderError
errors.AccessDenied
errors.InvalidRequest
errors.InteractionRequired
// …and ~30 more named error classes

Throw these inside custom interaction routes, adapter methods, or findAccount to signal structured OAuth error responses back to clients. Each class sets the correct error and error_description fields automatically.

interactionPolicy

import { interactionPolicy } from './src/oidc/index.js';

const { base, Prompt, Check } = interactionPolicy;
// base() → default policy array [login prompt, consent prompt]
// new Prompt(name, ...checks)
// new Check(reason, description, fn)

Use interactionPolicy to define when the provider should redirect users to your login/consent UI. Replace or extend the default base() policy with custom Prompt and Check instances.

ExternalSigningKey

import { ExternalSigningKey } from './src/oidc/index.js';

new ExternalSigningKey({ kid: string, alg: string, key: KeyLike | CryptoKey })

Pass an ExternalSigningKey instance inside the jwks configuration when your private signing key is stored in an HSM, KMS, or is otherwise not directly exportable. The provider delegates signing to the key object without ever holding the raw private key bytes.

Working examples

Scenario - Minimal server with in-memory adapter

A quick local development server that serves all OIDC endpoints with a single hardcoded client.

import http from 'node:http';
import Provider from './src/oidc/index.js';
import MemoryAdapter from './src/oidc/adapters/memory_adapter.js';

const provider = new Provider('http://localhost:3000', {
  adapter: MemoryAdapter,
  clients: [
    {
      client_id: 'app',
      client_secret: 'secret',
      redirect_uris: ['http://localhost:8080/cb'],
      grant_types: ['authorization_code', 'refresh_token'],
      response_types: ['code'],
    },
  ],
  jwks: {
    keys: [
      // paste a private RSA or EC JWK here
    ],
  },
  scopes: ['openid', 'profile', 'email', 'offline_access'],
  async findAccount(_ctx, id) {
    return {
      accountId: id,
      async claims() { return { sub: id, email: `${id}@example.com` }; },
    };
  },
});

http.createServer(provider.callback()).listen(3000, () => {
  console.log('OIDC provider listening on http://localhost:3000');
  console.log('Discovery: http://localhost:3000/.well-known/openid-configuration');
});

Scenario - Custom interaction policy (force login every time)

Override the default interaction policy to always require a fresh login, ignoring existing sessions.

import Provider from './src/oidc/index.js';
import { interactionPolicy } from './src/oidc/index.js';

const { base, Check } = interactionPolicy;

const policy = base();
const loginPrompt = policy.get('login');

loginPrompt.checks.add(
  new Check(
    'session_expired',
    'End-User session is too old; re-authentication required.',
    (ctx) => {
      const { oidc } = ctx;
      if (oidc.session?.accountId) {
        const age = (Date.now() / 1000) - oidc.session.loginTs;
        if (age > 900) return Check.REQUEST_PROMPT; // 15-minute max session age
      }
      return Check.NO_NEED_TO_PROMPT;
    },
  ),
);

const provider = new Provider('https://auth.example.com', {
  interactions: { policy },
  // …other config
});

Scenario - Throwing structured errors from a custom grant or adapter

Use the errors namespace inside adapter or custom logic to produce well-formed OAuth error responses.

import { errors } from './src/oidc/index.js';

async function findAccount(ctx, sub) {
  const user = await db.users.findOne({ sub });

  if (!user) {
    throw new errors.InvalidRequest('account not found');
  }

  if (user.suspended) {
    throw new errors.AccessDenied('account is suspended', 403);
  }

  return {
    accountId: user.sub,
    async claims(use, scope) {
      return { sub: user.sub, email: user.email };
    },
  };
}

File walkthrough

• index.js - Re-exports Provider, errors, interactionPolicy, ExternalSigningKey; performs runtime version check.
• provider.js - Instantiates and configures the Koa app; registers all route stacks from actions/.
• actions/index.js - Aggregates and exports all endpoint factory functions used by provider.js.
• actions/authorization/index.js - Composes the 50+ step middleware pipeline for /auth, /device_authorization, PAR, and resume endpoints.
• actions/grants/index.js - Named exports for each grant type handler; consumed by actions/token.js.
• adapters/memory_adapter.js - Reference in-memory adapter; not suitable for production or multi-process deployments.
• consts/index.js - Exports PARAM_LIST, PUSHED_REQUEST_URN, CLIENT_ATTRIBUTES, DEV_KEYSTORE, JWA.
• helpers/ - Internal error classes, interaction policy constructors, weak-cache for per-provider state, keystore helpers.
• models/ - Token lifecycle models (mint, find, consume, destroy) used by grant handlers.
• response_modes/ - Pluggable response mode implementations written as Koa middleware.
• shared/ - Generic middleware (session loading, body parsing, resource indicator checks, duplicate param rejection).
• views/ - ETA HTML templates for built-in fallback UI pages; override by providing renderError and interaction redirects.

Common pitfalls and fixes

• CJS project importing ESM source: require() of this source will throw ERR_REQUIRE_ESM. Fix: add "type": "module" to package.json or use dynamic import() inside an async wrapper.
• Node.js version below v22 LTS: The library logs a warning and certain Web Crypto APIs may be absent. Fix: use node:22 (or the node:lts Docker tag).
• Missing jwks configuration: The provider will refuse to start or fail to sign tokens. Fix: always supply at least one private RSA (RS256) or EC (ES256) JWK in configuration.jwks.keys.
• In-memory adapter across processes / restarts: All tokens are lost on restart and sessions are not shared across workers. Fix: implement a Redis- or database-backed adapter following the eight-method interface.
• Interaction route not consuming the interaction: If your login UI calls provider.interactionFinished with an incorrect result shape, the user gets an infinite redirect loop. Fix: return { login: { accountId: string } } for login and { consent: { rejectedScopes: [], rejectedClaims: [] } } for consent.
• PKCE required by default for public clients: Public clients without code_challenge will receive invalid_request. Fix: either pass code_challenge_method and code_challenge in the authorization request, or explicitly configure features.pkce.required to return false for your client type.

Vibe-coding prompt template

I have the oidc-provider library source code located at `src/oidc/` in my project.
A usage guide is in `USAGE.md`. The upstream package is `user@example.com` (ESM only, Node.js v22+ required).

Please help me integrate this into my existing Express/Node.js project step by step:

1. Read `USAGE.md` and `src/oidc/index.js` to understand available exports.
2. Create `src/oidc-config.js` that instantiates a `Provider` using the real `Provider` export,
   wires my existing database as an adapter (8-method interface), configures `jwks` from
   the `JWKS_JSON` env var, and exports the provider instance.
3. Mount the provider on my Express app using `provider.callback()` under the path `/oidc`.
4. Add a `/interaction/:uid` route that reads the current interaction with
   `provider.interactionDetails(req, res)` and calls `provider.interactionFinished` after login.
5. Use `errors.InvalidRequest` and `errors.AccessDenied` from `src/oidc/index.js` for
   structured error responses in my findAccount implementation.
6. Do not invent any APIs; only use symbols documented in USAGE.md and visible in src/oidc/index.js.

License and credit

oidc-provider is licensed under the MIT License. See source/LICENSE if present, or refer to the npm package page and the upstream repository maintained by Filip Skokan.

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.