openid-client

The openid-client library provides a comprehensive set of tools for implementing OpenID Connect (OIDC) and OAuth 2.0 flows. The API is organized into several functional areas:

• Grants: Implementation of various OAuth 2.0 flows including authorizationCodeGrant, clientCredentialsGrant, refreshTokenGrant, initiateDeviceAuthorization, and initiateBackchannelAuthentication (CIBA).
• Authorization Request: Utilities for constructing requests, such as buildAuthorizationUrl, calculatePKCECodeChallenge, and generating randomNonce or randomState.
• Configuration: Methods for global and instance-specific settings via discovery and the Configuration class.
• Client Authentication: Support for multiple methods including ClientSecretBasic, ClientSecretJwt, ClientSecretPost, PrivateKeyJwt, and TlsClientAuth.
• Protected Resource Requests: Methods to interact with APIs using tokens, such as fetchProtectedResource and fetchUserInfo.
• Token Management: Tools for tokenIntrospection and tokenRevocation.
• Security Extensions: Support for DPoP (Demonstrating Proof-of-Possession) and PKCE (Proof Key for Code Exchange).

The Configuration class is an abstraction that combines OAuth 2.0 Authorization Server metadata and OAuth 2.0 Client metadata. It serves as the central object for interacting with an OpenID Provider.

You can obtain a Configuration instance in two ways:

1. Discovery (Recommended): Use the discovery function to automatically fetch the Authorization Server metadata using the Issuer Identifier.
2. Constructor: Use the new Configuration() constructor if you already have the Server Metadata available upfront.

// Recommended: Using discovery
let server!: URL
let clientId!: string
let clientSecret!: string | undefined

let config = await client.discovery(server, clientId, clientSecret)

// Alternative: Using the constructor
let serverMetadata!: client.ServerMetadata
let clientId!: string
let clientSecret!: string | undefined

let config = new client.Configuration(serverMetadata, clientId, clientSecret)

Setting use_mtls_endpoint_aliases to true in ClientMetadata indicates that the client must use mutual TLS endpoint aliases provided by the Authorization Server.

To implement this, you must combine this setting with customFetch to provide a fetch implementation that supports client certificates (e.g., using undici in Node.js or Deno.createHttpClient in Deno). This is used to target security profiles utilizing Mutual-TLS for client authentication or sender-constrained tokens (RFC 8705).

### (Node.js) Using nodejs/undici for Mutual-TLS
```ts
import * as undici from 'undici'

let config!: client.Configuration
let key!: string // PEM-encoded key
let cert!: string // PEM-encoded certificate

let agent = new undici.Agent({ connect: { key, cert } })

config[client.customFetch] = (...args) =>
  // @ts-expect-error
  undici.fetch(args[0], { ...args[1], dispatcher: agent })

(Deno) Using Deno.createHttpClient for Mutual-TLS

let config!: client.Configuration
let key!: string // PEM-encoded key
let cert!: string // PEM-encoded certificate

// @ts-expect-error
let agent = Deno.createHttpClient({ key, cert })

config[client.customFetch] = (...args) =>
  // @ts-expect-error
  fetch(args[0], { ...args[1], client: agent })

The Authorization Code flow is used to obtain Access Tokens (and optionally Refresh Tokens) for end-users. The process involves two main steps:

1. Redirecting the user: Generate an authorization URL using buildAuthorizationUrl. It is highly recommended to use PKCE (Proof Key for Code Exchange). You must generate a code_verifier and a code_challenge, and store the code_verifier and state in the user's session to recover them after the redirect.

2. Exchanging the code: Once the user is redirected back to your redirect_uri, use authorizationCodeGrant to exchange the authorization code for tokens, providing the stored pkceCodeVerifier and expectedState.

/**
 * Step 1: Build the authorization URL
 */
let redirect_uri!: string
let scope!: string
let code_verifier: string = client.randomPKCECodeVerifier()
let code_challenge: string = await client.calculatePKCECodeChallenge(code_verifier)
let state!: string

let parameters: Record<string, string> = {
  redirect_uri,
  scope,
  code_challenge,
  code_challenge_method: 'S256',
}

if (!config.serverMetadata().supportsPKCE()) {
  state = client.randomState()
  parameters.state = state
}

let redirectTo: URL = client.buildAuthorizationUrl(config, parameters)
// Redirect the user to redirectTo.href

/**
 * Step 2: Exchange code for tokens
 */
let tokens: client.TokenEndpointResponse = await client.authorizationCodeGrant(
  config,
  getCurrentUrl(),
  {
    pkceCodeVerifier: code_verifier,
    expectedState: state,
  },
)