openid-client

OAuth 2 / OpenID Connect Client API for JavaScript Runtimes

openid-client simplifies integration with authorization servers by providing easy-to-use APIs for the most common authentication and authorization flows, including OAuth 2 and OpenID Connect. It is designed for JavaScript runtimes like Node.js, Browsers, Deno, Cloudflare Workers, and more.

Features

The following features are currently in scope and implemented in this software:

• Authorization Server Metadata discovery
• Authorization Code Flow (profiled under OpenID Connect 1.0, OAuth 2.0, OAuth 2.1, FAPI 1.0 Advanced, and FAPI 2.0)
• Refresh Token, Device Authorization, and Client Credentials Grants
• Demonstrating Proof-of-Possession at the Application Layer (DPoP)
• Token Introspection and Revocation
• Pushed Authorization Requests (PAR)
• UserInfo and Protected Resource Requests
• Authorization Server Issuer Identification
• JWT Secured Introspection, Response Mode (JARM), Authorization Request (JAR), and UserInfo
• Passport Strategy

Sponsor

If you want to quickly add authentication to JavaScript apps, feel free to check out Auth0's JavaScript SDK and free plan. Create an Auth0 account; it's free!

Certification

Filip Skokan has certified that this software conforms to the Basic, FAPI 1.0, and FAPI 2.0 Relying Party Conformance Profiles of the OpenID Connect™ protocol.

💗 Help the project

Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by becoming a sponsor.

API Reference Documentation

openid-client is distributed via npmjs.com and github.com.

Examples

example ESM import

1import * as client from 'openid-client'

• Authorization Code Flow (OAuth 2.0) - source
• Authorization Code Flow (OpenID Connect) - source | diff
• Extensions
  • JWT Secured Authorization Request (JAR) - source | diff
  • JWT Secured Authorization Response Mode (JARM) - source | diff
  • Pushed Authorization Request (PAR) - source | diff
• Passport Strategy - source

Quick start

1let server!: URL // Authorization Server's Issuer Identifier
2let clientId!: string // Client identifier at the Authorization Server
3let clientSecret!: string // Client Secret
4
5let config: client.Configuration = await client.discovery(
6  server,
7  clientId,
8  clientSecret,
9)

Authorization Code Flow

Authorization Code flow is for obtaining Access Tokens (and optionally Refresh Tokens) to use with third party APIs.

When you want to have your end-users authorize or authenticate you need to send them to the authorization server's authorization_endpoint. Consult the web framework of your choice on how to redirect but here's how to get the authorization endpoint's URL with parameters already encoded in the query to redirect to.

1/**
2 * Value used in the authorization request as the redirect_uri parameter, this
3 * is typically pre-registered at the Authorization Server.
4 */
5let redirect_uri!: string
6let scope!: string // Scope of the access request
7/**
8 * PKCE: The following MUST be generated for every redirect to the
9 * authorization_endpoint. You must store the code_verifier and state in the
10 * end-user session such that it can be recovered as the user gets redirected
11 * from the authorization server back to your application.
12 */
13let code_verifier: string = client.randomPKCECodeVerifier()
14let code_challenge: string =
15  await client.calculatePKCECodeChallenge(code_verifier)
16let state!: string
17
18let parameters: Record<string, string> = {
19  redirect_uri,
20  scope,
21  code_challenge,
22  code_challenge_method: 'S256',
23}
24
25if (!config.serverMetadata().supportsPKCE()) {
26  /**
27   * We cannot be sure the server supports PKCE so we're going to use state too.
28   * Use of PKCE is backwards compatible even if the AS doesn't support it which
29   * is why we're using it regardless. Like PKCE, random state must be generated
30   * for every redirect to the authorization_endpoint.
31   */
32  state = client.randomState()
33  parameters.state = state
34}
35
36let redirectTo: URL = client.buildAuthorizationUrl(config, parameters)
37
38// now redirect the user to redirectTo.href
39console.log('redirecting to', redirectTo.href)

When end-users are redirected back to the redirect_uri your application consumes the callback and passes in PKCE code_verifier to include it in the authorization code grant token exchange.

1let getCurrentUrl!: (...args: any) => URL
2
3let tokens: client.TokenEndpointResponse = await client.authorizationCodeGrant(
4  config,
5  getCurrentUrl(),
6  {
7    pkceCodeVerifier: code_verifier,
8    expectedState: state,
9  },
10)
11
12console.log('Token Endpoint Response', tokens)

You can then fetch a protected resource response

1let protectedResourceResponse: Response = await client.fetchProtectedResource(
2  config,
3  tokens.access_token,
4  new URL('https://rs.example.com/api'),
5  'GET',
6)
7
8console.log(
9  'Protected Resource Response',
10  await protectedResourceResponse.json(),
11)

Device Authorization Grant (Device Flow)

1let scope!: string // Scope of the access request
2
3let response = await client.initiateDeviceAuthorization(config, { scope })
4
5console.log('User Code:', response.user_code)
6console.log('Verification URI:', response.verification_uri)
7console.log('Verification URI (complete):', response.verification_uri_complete)

You will display the instructions to the end-user and have them directed at verification_uri or verification_uri_complete, afterwards you can start polling for the Device Access Token Response.

1let tokens: client.TokenEndpointResponse =
2  await client.pollDeviceAuthorizationGrant(config, response)
3
4console.log('Token Endpoint Response', tokens)

This will poll in a regular interval and only resolve with tokens once the end-user authenticates.

Client Credentials Grant

Client Credentials flow is for obtaining Access Tokens to use with third party APIs on behalf of your application, rather than an end-user which was the case in previous examples.

1let scope!: string // Scope of the access request
2let resource!: string // Resource Indicator of the Resource Server the access token is for
3
4let tokens: client.TokenEndpointResponse = await lib.clientCredentialsGrant(
5  config,
6  { scope, resource },
7)
8
9console.log('Token Endpoint Response', tokens)

Supported Runtimes

The supported JavaScript runtimes include those that support the utilized Web API globals and standard built-in objects. These are (but are not limited to):

• Browsers
• Bun
• Cloudflare Workers
• Deno
• Electron
• Node.js¹
• Vercel's Edge Runtime

Supported Versions

Version	Security Fixes 🔑	Other Bug Fixes 🐞	New Features ⭐	Runtime and Module type
v6.x	✅	✅	✅	Universal2 ESM3
v5.x	✅	❌	❌	Node.js CJS + ESM

Footnotes

1. Node.js v20.x as baseline is required ↩

2. Assumes runtime support of WebCryptoAPI and Fetch API ↩

3. CJS style require('openid-client') is possible in Node.js versions where process.features.require_module is true or with the --experimental-require-module Node.js CLI flag. ↩