Registry / auth-security / openid-client

openid-client

library6.8.3jsnpmunverified

openid-client is an OpenID Certified JavaScript client library designed for implementing OAuth 2.0 and OpenID Connect flows. It offers a comprehensive API for common authentication and authorization patterns, including Authorization Code, Refresh Token, Device Authorization, Client-Initiated Backchannel Authentication (CIBA), and Client Credentials grants. The library also supports advanced features like Demonstrating Proof-of-Possession (DPoP), Token Introspection and Revocation, Pushed Authorization Requests (PAR), and various JWT Secured operations (JAR, JARM, UserInfo). It is built for a wide range of JavaScript runtimes, including Node.js, browsers, Deno, and Cloudflare Workers. Currently at version 6.8.3, openid-client is actively maintained with a regular release cadence, ensuring compliance with the latest protocol specifications. A key differentiator is its OpenID Certification for Basic, FAPI 1.0, and FAPI 2.0 Relying Party Conformance Profiles, guaranteeing high standards of protocol interoperability.

auth-security http-networking web-framework

npm install openid-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENID-CLIENT

openid-client

auth-securityjavascriptv6.8.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

discovery

✓ import { discovery } from 'openid-client'

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

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

Client

✓ import { Client } from 'openid-client'

✗ import Client from 'openid-client'

Client is a named export, not a default export. Typically used after issuer discovery.

generators

✓ import { generators } from 'openid-client'

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

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

All exports

✓ import * as openid from 'openid-client'

✗ const openid = require('openid-client')

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

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();

Debug

Known issues

breakingSince 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.

affects: >=5.0.0

gotchaWhen 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.

affects: >=6.8.3

gotchaThe 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.

affects: >=6.6.3

breakingWhen 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.

affects: >=6.8.3

Errors

Common errors & fixes

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

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

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

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.

Upgrade

Version history

6.8.3latest on npm

Audit

Dependencies

passportoptionalRequired only when integrating with Passport.js using the provided Passport Strategy.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/panva/openid-client ↗

packagehttps://www.npmjs.com/package/openid-client ↗

homepagehttps://openid.net/openid-client/ ↗