OpenID Connect Client

Common errors

• TypeError: (0, openid_client_1.discovery) is not a function

  cause Attempting to use `require()` to import `openid-client` in a CommonJS module, or running an ESM module without proper configuration (e.g., missing `"type": "module"` in `package.json` or incorrect file extension).
  fix Ensure your project is configured for ES Modules. Use `import { discovery } from 'openid-client'` and add `"type": "module"` to your `package.json` or rename your file to `.mjs`.

• Error: authorization_code grant type not allowed for this client

  cause The client registered with the Authorization Server does not have the 'authorization_code' grant type enabled or the 'response_types' are misconfigured.
  fix Verify your client registration at the Authorization Server to ensure 'authorization_code' is an allowed grant type and 'code' is an allowed response type. Double-check `client.response_types` configuration.

• Error: invalid_grant

  cause The authorization code exchanged for tokens is invalid, expired, or has already been used. This can also happen due to PKCE mismatch.
  fix Ensure the `code_verifier` sent during the token exchange matches the `code_challenge` sent during the authorization request. Also, ensure the authorization code is used only once and within its validity period. Check the redirect URI matching exactly.

Warnings

• breaking Since v5, openid-client is a pure ECMAScript Module (ESM). Attempting to use `require()` for imports will result in a TypeError.
  Fix: Migrate your project to use ES Modules with `import` statements. Ensure your `package.json` includes `"type": "module"` or use `.mjs` file extensions.
• gotcha When using `redirect_uri` with a query string or a bare origin, there are known subtle issues that may require a specific workaround documented by the library.
  Fix: Refer to the official documentation or the changelog entry (v6.8.3) for the recommended workaround regarding `redirect_uri` construction. Prefer full, unambiguous URLs without extraneous query parameters unless specifically handled.
• gotcha The Passport strategy integration (e.g., in Express.js apps) may now require custom logic to drive initiating authentication requests, affecting previous implementations that relied on implicit request handling.
  Fix: Review the Passport strategy documentation and examples. You may need to update how you trigger the authentication flow, potentially passing `req.host` explicitly in older Express environments (v6.7.1) or defining custom logic.
• breaking When using the Passport strategy, a fix was implemented to correctly delete one-time state on callback, which might alter behavior for applications expecting state to persist or for those that didn't correctly clean up state previously.
  Fix: Ensure your application's state management for Passport callbacks is robust and handles the expected deletion of one-time state, especially if you had custom state persistence logic.

Install

• npm install openid-client npm
• yarn add openid-client yarn
• pnpm add openid-client pnpm

Imports

• discovery
  wrong:

  const { discovery } = require('openid-client')

  correct:

  import { discovery } from 'openid-client'

  openid-client is a pure ESM module since v5. CommonJS 'require' syntax will result in a TypeError.
• Client
  wrong:

  import Client from 'openid-client'

  correct:

  import { Client } from 'openid-client'

  Client is a named export, not a default export. Typically used after issuer discovery.
• generators
  wrong:

  import * as generators from 'openid-client/lib/helpers/generators'

  correct:

  import { generators } from 'openid-client'

  The generators for state, nonce, and PKCE verifiers are named exports from the top-level module path.
• All exports
  wrong:

  const openid = require('openid-client')

  correct:

  import * as openid from 'openid-client'

  This pattern imports all named exports into an 'openid' namespace. For ESM environments only.

Quickstart

This quickstart demonstrates how to discover an OpenID Provider, register a client, and generate an authorization URL for the Authorization Code Flow with PKCE and OIDC.

import { Issuer, generators } from 'openid-client';

const main = async () => {
  const issuerUrl = process.env.OIDC_ISSUER_URL ?? 'https://accounts.google.com';
  const clientId = process.env.OIDC_CLIENT_ID ?? 'YOUR_CLIENT_ID';
  const clientSecret = process.env.OIDC_CLIENT_SECRET ?? 'YOUR_CLIENT_SECRET';
  const redirectUri = process.env.OIDC_REDIRECT_URI ?? 'http://localhost:3000/callback';

  try {
    // Discover the OpenID Provider's configuration
    const googleIssuer = await Issuer.discover(issuerUrl);
    console.log('Discovered issuer: %s %O', googleIssuer.issuer, googleIssuer.metadata);

    // Register a new client with the issuer
    const client = new googleIssuer.Client({
      client_id: clientId,
      client_secret: clientSecret,
      redirect_uris: [redirectUri],
      response_types: ['code'],
    });

    // Generate parameters for the authorization request
    const code_verifier = generators.codeVerifier();
    const code_challenge = generators.codeChallenge(code_verifier);
    const state = generators.state();
    const nonce = generators.nonce();

    const authorizationUrl = client.authorizationUrl({
      scope: 'openid email profile',
      code_challenge,
      code_challenge_method: 'S256',
      state,
      nonce,
      redirect_uri: redirectUri,
    });

    console.log(`
Navigate to this URL to start the login flow:\n${authorizationUrl}
`);

  } catch (error) {
    console.error('Error during OpenID Connect setup:', error);
  }
};

main();