Class: OIDCClient

OIDCClient(config)

OpenID Connect Relying Party for a PUBLIC client (a browser app): Authorization Code + PKCE, with the protections RFC 9700 (OAuth 2.0 Security Best Current Practice) and OpenID Connect call for. It holds no client secret and supports no confidential-client authentication.

Emits: "tokens" (TokenSet) whenever the token endpoint issues new tokens.

Constructor

new OIDCClient(config)

Parameters:
Name Type Description
config OIDCClientConfig
Source:

Classes

OIDCClient

Members

config

The effective settings, for display.

Source:

dpopKey :DPoPKey|undefined

Type:
Source:

metadata :Record.<string, any>

Type:
  • Record.<string, any>
Source:

securityFeatures

Which security features are active, for display and audit.

Source:

Methods

(async) callback(response) → {Promise.<TokenSet>}

Completes the sign-in from the redirect: consumes the stored transaction for the returned state (single use), checks it, redeems the code with the PKCE verifier (and a DPoP proof) and validates the ID token.

Parameters:
Name Type Description
response URLSearchParams | Record.<string, string> | string

The redirect URL, or its query parameters.
Source:
Returns:
Type
Promise.<TokenSet>

(async) completeAuthorization(response) → {Promise.<{tokenSet: TokenSet, context: any}>}

callback(), also answering the context the request was created with. An error the OP returned (e.g. login_required or account_selection_required to a prompt=none request) is thrown as an OAuthError carrying that context as err.context.

Parameters:
Name Type Description
response URLSearchParams | Record.<string, string> | string
Source:
Returns:
Type
Promise.<{tokenSet: TokenSet, context: any}>

(async) completeEndSession(response) → {Promise.<{context: any}>}

validateEndSessionCallback(), answering the context the logout request was created with.

Parameters:
Name Type Description
response URLSearchParams | Record.<string, string> | string
Source:
Returns:
Type
Promise.<{context: any}>

(async) createAuthorizationRequest(optsopt) → {Promise.<{url: string, state: string}>}

Starts an Authorization Code + PKCE (S256) sign-in. The transaction (state, nonce, code verifier) is stored in the transaction store under its state, and callback() consumes it. Uses PAR when enabled, and binds the authorization code to the DPoP key (dpop_jkt).

Parameters:
Name Type Attributes Description
opts object <optional>
Properties
Name Type Attributes Description
scope string <optional>
redirectUri string <optional>
prompt string <optional>
maxAge number <optional>
loginHint string <optional>
idTokenHint string <optional>

A previously issued ID token naming the account (and session) meant.
acrValues string <optional>

Space-separated; with enforceAcr, the ID token's acr must be one of these.
expectedSub string <optional>

The callback refuses an ID token about anybody else (account_mismatch): when a request names an account, a sign-in as another person must not be taken for it.
context any <optional>

JSON-serialisable data kept with the transaction and handed back by completeAuthorization() (and on an OAuthError as err.context).
extraParams Record.<string, string> <optional>
Source:
Returns:
Type
Promise.<{url: string, state: string}>

(async) createEndSessionRequest(optsopt) → {Promise.<({url: string, state: string}|undefined)>}

Builds an RP-Initiated Logout 1.0 request with a fresh state, stored for validateEndSessionCallback(). Resolves undefined when the OP has no end_session_endpoint. context is kept with the state and handed back by completeEndSession().

Parameters:
Name Type Attributes Description
opts Object <optional>

(TypeScript: { idTokenHint?: string, postLogoutRedirectUri?: string, logoutHint?: string, context?: any })
Source:
Returns:
Type
Promise.<({url: string, state: string}|undefined)>

(async) fetchResource(token, url, initopt)

fetch() against a protected resource with an access token, retrying once when the resource server asks for a DPoP nonce (RFC 9449 §9).

Parameters:
Name Type Attributes Description
token *

(TypeScript: TokenSet|{access_token: string, token_type?: string}|string)
url string
init RequestInit <optional>
Source:

(async) refresh(tokenSetOrRefreshToken, optsopt)

Refresh Token grant (OIDC Core §12). Keeps the previous refresh token when the OP doesn't rotate it, validates any new ID token against the previous claims (§12.2), and sends a DPoP proof with the same key when the tokens are DPoP-bound.

With a bare refresh token string there are no previous claims to hold a new ID token to, so pass previousClaims (the claims of the ID token from the original sign-in); without them a response that carries an ID token is refused.

Parameters:
Name Type Attributes Description
tokenSetOrRefreshToken TokenSet | string
opts Object <optional>

(TypeScript: { scope?: string, previousClaims?: object })
Source:

(async) resourceHeaders(token, request) → {Promise.<Record.<string, string>>}

The Authorization (and DPoP) headers for a request to a resource server with an access token. A DPoP-bound token (token_type "DPoP") gets a fresh proof bound to this method, URL and token.

Parameters:
Name Type Description
token *

(TypeScript: TokenSet|{access_token: string, token_type?: string}|string)
request Object

(TypeScript: { method?: string, url: string, nonce?: string })
Source:
Returns:

authorization, and dpop for a DPoP-bound token

Type
Promise.<Record.<string, string>>

(async) revoke(token, hintopt)

Token revocation (RFC 7009), as a public client. Resolves false when the OP has no revocation endpoint.

Parameters:
Name Type Attributes Description
token string
hint 'access_token' | 'refresh_token' <optional>
Source:

(async) userinfo(token, optsopt)

Calls the UserInfo endpoint (OIDC Core §5.3). The response must be about the person the ID token is about (§5.3.2): its sub is checked against expectedSub, or else the TokenSet's ID token sub. With a bare access token and no expectedSub there is nothing to check against, so it is refused.

Parameters:
Name Type Attributes Description
token *

(TypeScript: TokenSet|{access_token: string, token_type?: string}|string)
opts Object <optional>

(TypeScript: { expectedSub?: string })
Source:

(async) validateEndSessionCallback(response)

Checks the state the OP returned to the post-logout redirect URI. Throws when it is missing, unknown, reused or expired.

Parameters:
Name Type Description
response URLSearchParams | Record.<string, string> | string
Source:

(async) validateIdToken(idToken, optsopt) → {Promise.<Record.<string, any>>}

Parameters:
Name Type Attributes Description
idToken string
opts Object <optional>

(TypeScript: { nonce?: string, maxAge?: number, acrValues?: string, accessToken?: string, previousClaims?: object })
Source:
Returns:

the validated claims

Type
Promise.<Record.<string, any>>

(async, static) discover(config) → {Promise.<OIDCClient>}

Creates a client and loads the provider's discovery document.

Parameters:
Name Type Description
config OIDCClientConfig
Source:
Returns:
Type
Promise.<OIDCClient>

(async, static) fromMetadata(metadata, config) → {Promise.<OIDCClient>}

Creates a client from an already-obtained OpenID Provider metadata document (validated as if discovered).

Parameters:
Name Type Description
metadata Record.<string, any>
config Omit.<OIDCClientConfig, 'metadata'>
Source:
Returns:
Type
Promise.<OIDCClient>

(async, static) register(providerMetadata, clientMetadata, configopt) → {Promise}

Registers a new PUBLIC client (OpenID Connect Dynamic Client Registration 1.0) and returns a client configured from the registration. token_endpoint_auth_method is always "none".

Parameters:
Name Type Attributes Description
providerMetadata Record.<string, any>
clientMetadata Record.<string, any>

RFC 7591 metadata, e.g. { redirect_uris, id_token_signed_response_alg }
config * <optional>

(TypeScript: Omit<OIDCClientConfig, 'clientId' | 'metadata'> & { initialAccessToken?: string })
Source:
Returns:

(TypeScript: Promise<{ client: OIDCClient, registration: import('./registration.js').ClientRegistration }>)

Type
Promise