Class OIDCClient

constructor

• new OIDCClient(config: OIDCClientConfig): OIDCClient

  Parameters

  • config: OIDCClientConfig

  Returns OIDCClient

dpopKey

metadata

clientId

• get clientId(): string

  Returns string

config

• get config(): {
      allowInsecureRequests: boolean;
      clientId: string;
      clockToleranceSec: number;
      discoveryCacheTtlMs?: number;
      dpop: boolean;
      enforceAcr: boolean;
      httpTimeoutMs: number;
      idTokenSignedResponseAlg: string;
      issuer: any;
      maxIdTokenAgeSec: number;
      par: boolean;
      postLogoutRedirectUri?: string;
      redirectUri?: string;
      requireAuthTime: boolean;
      requireDpop: boolean;
      resource?: string
      | string[];
      scope?: string;
      tokenEndpointAuthMethod: string;
      transactionTtlSec: number;
      userinfoSignedResponseAlg?: string;
  }

  The effective settings, for display.

  Returns {
      allowInsecureRequests: boolean;
      clientId: string;
      clockToleranceSec: number;
      discoveryCacheTtlMs?: number;
      dpop: boolean;
      enforceAcr: boolean;
      httpTimeoutMs: number;
      idTokenSignedResponseAlg: string;
      issuer: any;
      maxIdTokenAgeSec: number;
      par: boolean;
      postLogoutRedirectUri?: string;
      redirectUri?: string;
      requireAuthTime: boolean;
      requireDpop: boolean;
      resource?: string | string[];
      scope?: string;
      tokenEndpointAuthMethod: string;
      transactionTtlSec: number;
      userinfoSignedResponseAlg?: string;
  }

  • allowInsecureRequests: boolean

  • clientId: string

    A PUBLIC client (token_endpoint_auth_method "none").

  • clockToleranceSec: number

  • OptionaldiscoveryCacheTtlMs?: number

    How long discovered metadata is cached (default 1h).

  • dpop: boolean

  • enforceAcr: boolean

  • httpTimeoutMs: number

  • idTokenSignedResponseAlg: string

  • issuer: any

  • maxIdTokenAgeSec: number

  • par: boolean

  • OptionalpostLogoutRedirectUri?: string

  • OptionalredirectUri?: string

  • requireAuthTime: boolean

  • requireDpop: boolean

  • Optionalresource?: string | string[]

    RFC 8707 resource indicator(s): audience-restricts the tokens.

  • Optionalscope?: string

    Default "openid profile email offline_access" (offline_access only if supported).

  • tokenEndpointAuthMethod: string

  • transactionTtlSec: number

  • OptionaluserinfoSignedResponseAlg?: string

    The only alg a signed UserInfo response may use. Default: any asymmetric algorithm.

issuer

• get issuer(): any

  Returns any

securityFeatures

• get securityFeatures(): {
      dpop: boolean
      | { alg: string; jkt: string };
      idToken: string;
      issuerIdentification: string;
      nonce: boolean;
      par: boolean;
      pkce: string;
      resourceIndicators: boolean | never[];
      state: string;
      tlsEnforced: boolean;
  }

  Which security features are active, for display and audit.

  Returns {
      dpop: boolean | { alg: string; jkt: string };
      idToken: string;
      issuerIdentification: string;
      nonce: boolean;
      par: boolean;
      pkce: string;
      resourceIndicators: boolean | never[];
      state: string;
      tlsEnforced: boolean;
  }

callback

• callback(
      response: string | Record<string, string> | URLSearchParams,
  ): 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

  • response: string | Record<string, string> | URLSearchParams

    The redirect URL, or its query parameters.

  Returns Promise<TokenSet>

completeAuthorization

• completeAuthorization(
      response: string | Record<string, string> | URLSearchParams,
  ): Promise<{ context: any; tokenSet: TokenSet }>

  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

  • response: string | Record<string, string> | URLSearchParams

  Returns Promise<{ context: any; tokenSet: TokenSet }>

completeEndSession

• completeEndSession(
      response: string | Record<string, string> | URLSearchParams,
  ): Promise<{ context: any }>

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

  Parameters

  • response: string | Record<string, string> | URLSearchParams

  Returns Promise<{ context: any }>

createAuthorizationRequest

• createAuthorizationRequest(
      opts?: {
          acrValues?: string;
          context?: any;
          expectedSub?: string;
          extraParams?: Record<string, string>;
          idTokenHint?: string;
          loginHint?: string;
          maxAge?: number;
          prompt?: string;
          redirectUri?: string;
          scope?: string;
      },
  ): Promise<{ state: string; url: 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

  • Optionalopts: {
        acrValues?: string;
        context?: any;
        expectedSub?: string;
        extraParams?: Record<string, string>;
        idTokenHint?: string;
        loginHint?: string;
        maxAge?: number;
        prompt?: string;
        redirectUri?: string;
        scope?: string;
    } = {}

    • OptionalacrValues?: string

      Space-separated; with enforceAcr, the ID token's acr must be one of these.

    • Optionalcontext?: any

      JSON-serialisable data kept with the transaction and handed back by completeAuthorization() (and on an OAuthError as err.context).

    • OptionalexpectedSub?: string

      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.

    • OptionalextraParams?: Record<string, string>

    • OptionalidTokenHint?: string

      A previously issued ID token naming the account (and session) meant.

    • OptionalloginHint?: string

    • OptionalmaxAge?: number

    • Optionalprompt?: string

    • OptionalredirectUri?: string

    • Optionalscope?: string

  Returns Promise<{ state: string; url: string }>

createEndSessionRequest

• createEndSessionRequest(
      opts?: {
          context?: any;
          idTokenHint?: string;
          logoutHint?: string;
          postLogoutRedirectUri?: string;
      },
  ): Promise<{ state: string; url: 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

  • Optionalopts: {
        context?: any;
        idTokenHint?: string;
        logoutHint?: string;
        postLogoutRedirectUri?: string;
    } = {}

  Returns Promise<{ state: string; url: string } | undefined>

Staticdiscover

• discover(config: OIDCClientConfig): Promise<OIDCClient>

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

  Parameters

  • config: OIDCClientConfig

  Returns Promise<OIDCClient>

fetchResource

• fetchResource(
      token: string | TokenSet | { access_token: string; token_type?: string },
      url: string,
      init?: RequestInit,
  ): Promise<Response>

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

  Parameters

  • token: string | TokenSet | { access_token: string; token_type?: string }
  • url: string
  • Optionalinit: RequestInit = {}

  Returns Promise<Response>

StaticfromMetadata

• fromMetadata(
      metadata: Record<string, any>,
      config: Omit<OIDCClientConfig, "metadata">,
  ): Promise<OIDCClient>

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

  Parameters

  • metadata: Record<string, any>
  • config: Omit<OIDCClientConfig, "metadata">

  Returns Promise<OIDCClient>

init

• init(): Promise<OIDCClient>

  Returns Promise<OIDCClient>

refresh

• refresh(
      tokenSetOrRefreshToken: string | TokenSet,
      opts?: { previousClaims?: object; scope?: string },
  ): Promise<TokenSet>

  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

  • tokenSetOrRefreshToken: string | TokenSet
  • Optionalopts: { previousClaims?: object; scope?: string } = {}

  Returns Promise<TokenSet>

Staticregister

• register(
      providerMetadata: Record<string, any>,
      clientMetadata: Record<string, any>,
      config?: Omit<OIDCClientConfig, "metadata" | "clientId"> & {
          initialAccessToken?: string;
      },
  ): Promise<{ client: OIDCClient; registration: ClientRegistration }>

  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

  • providerMetadata: Record<string, any>
  • clientMetadata: Record<string, any>

    RFC 7591 metadata, e.g. { redirect_uris, id_token_signed_response_alg }

  • Optionalconfig: Omit<OIDCClientConfig, "metadata" | "clientId"> & {
        initialAccessToken?: string;
    } = {}

  Returns Promise<{ client: OIDCClient; registration: ClientRegistration }>

resourceHeaders

• resourceHeaders(
      token: string | TokenSet | { access_token: string; token_type?: string },
      request: { method?: string; nonce?: string; url: string },
  ): 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

  • token: string | TokenSet | { access_token: string; token_type?: string }
  • request: { method?: string; nonce?: string; url: string }

  Returns Promise<Record<string, string>>

  authorization, and dpop for a DPoP-bound token

revoke

• revoke(token: string, hint?: "refresh_token" | "access_token"): Promise<boolean>

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

  Parameters

  • token: string
  • Optionalhint: "refresh_token" | "access_token"

  Returns Promise<boolean>

userinfo

• userinfo(
      token: string | TokenSet | { access_token: string; token_type?: string },
      opts?: { expectedSub?: string },
  ): Promise<any>

  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

  • token: string | TokenSet | { access_token: string; token_type?: string }
  • Optionalopts: { expectedSub?: string } = {}

  Returns Promise<any>

validateEndSessionCallback

• validateEndSessionCallback(
      response: string | Record<string, string> | URLSearchParams,
  ): Promise<boolean>

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

  Parameters

  • response: string | Record<string, string> | URLSearchParams

  Returns Promise<boolean>

validateIdToken

• validateIdToken(
      idToken: string,
      opts?: {
          accessToken?: string;
          acrValues?: string;
          maxAge?: number;
          nonce?: string;
          previousClaims?: object;
      },
  ): Promise<Record<string, any>>

  Parameters

  • idToken: string
  • Optionalopts: {
        accessToken?: string;
        acrValues?: string;
        maxAge?: number;
        nonce?: string;
        previousClaims?: object;
    } = {}

  Returns Promise<Record<string, any>>

  the validated claims