OIDC Client

A generic OpenID Connect (OIDC) client library for JavaScript and TypeScript, designed to work with PingOne platforms.

The oidc module follows the OIDC specification and provides a simple and easy-to-use API to interact with the OIDC server. It allows you to authenticate, retrieve the access token, revoke the token, and sign out from the OIDC server.

Installation

pnpm add @forgerock/oidc-client
# or
npm install @forgerock/oidc-client
# or
yarn add @forgerock/oidc-client
Copy

Initialization

import { oidc } from '@forgerock/oidc-client';

const oidcClient = await oidc({
  config: {
    serverConfig: { wellknown: 'https://example.com/.well-known/openid-configuration' },
    clientId: 'example-client-id',
    redirectUri: 'https://example-app/redirect-uri',
    scope: 'openid profile email',
  },
});
Copy

API Reference

authorize

Methods for creating and handling authorization flows.

authorize.url(options?)

Creates an authorization URL with the provided options or defaults from the configuration.

• Parameters: GetAuthorizationUrlOptions (optional)
• Returns: Promise<string | GenericError> - The authorization URL or an error

const authUrl = await oidcClient.authorize.url();
if ('error' in authUrl) {
  console.error('Authorization URL creation failed:', authUrl.error);
}
Copy

authorize.background(options?)

Initiates the authorization process in the background, returning the authorization code and state or an error. This method handles the authorization flow without requiring user interaction.

• Parameters: GetAuthorizationUrlOptions (optional)
• Returns: Promise<AuthorizationSuccess | AuthorizationError> - An object containing code and state on success, or error details on failure

const authResponse = await oidcClient.authorize.background();
if ('error' in authResponse) {
  console.error('Authorization failed:', authResponse.error);
}
Copy

token

Methods for managing OAuth tokens.

token.exchange(code, state, options?)

Exchanges an authorization code for tokens using the token endpoint from the wellknown configuration. The tokens are automatically stored in the configured storage.

• Parameters:
  • code (string) - The authorization code received from the authorization server
  • state (string) - The state parameter from the authorization URL creation
  • options (Partial<StorageConfig>, optional) - Storage configuration for persisting tokens
• Returns: Promise<OauthTokens | TokenExchangeErrorResponse | GenericError> - The new tokens or an error

const tokens = await oidcClient.token.exchange(authCode, authState);
if ('error' in tokens) {
  console.error('Token exchange failed:', tokens.error);
}
Copy

token.get(options?)

Retrieves the current OAuth tokens from storage. Optionally auto-renews tokens if they are expired or if backgroundRenew is enabled.

• Parameters: GetTokensOptions (optional)
  • forceRenew - Force token renewal even if not expired
  • backgroundRenew - Automatically renew expired tokens
  • authorizeOptions - Options for authorization during renewal
  • storageOptions - Storage configuration options
• Returns: Promise<OauthTokens | TokenExchangeErrorResponse | AuthorizationError | GenericError> - The tokens or an error

const tokens = await oidcClient.token.get();
if ('error' in tokens) {
  console.error('Token retrieval failed:', tokens.error);
}
Copy

token.revoke()

Revokes the access token using the revocation endpoint from the wellknown configuration. Requires an access token stored in the configured storage.

• Parameters: None
• Returns: Promise<GenericError | RevokeSuccessResult | RevokeErrorResult> - Confirmation of revocation or an error

const response = await oidcClient.token.revoke();
if ('error' in response) {
  console.error('Token revocation failed:', response.error);
}
Copy

user

Methods for user information and session management.

user.info()

Retrieves user information using the userinfo endpoint from the wellknown configuration. Requires an access token stored in the configured storage.

• Parameters: None
• Returns: Promise<GenericError | UserInfoResponse> - User information object or an error

const user = await oidcClient.user.info();
if ('error' in user) {
  console.error('Failed to fetch user info:', user.error);
}
Copy

user.logout()

Logs out the user by revoking tokens and clearing the storage. Uses the end session endpoint from the wellknown configuration.

• Parameters: None
• Returns: Promise<GenericError | LogoutSuccessResult | LogoutErrorResult> - Confirmation of logout or an error

const logoutResponse = await oidcClient.user.logout();
if ('error' in logoutResponse) {
  console.error('Logout failed:', logoutResponse.error);
}
Copy