Class: MonoCloudOidcClient

Extends

MonoCloudOidcClientBase

Constructors

Constructor

new MonoCloudOidcClient(tenantDomain: string, clientId: string, options?: MonoCloudOidcClientOptions): MonoCloudOidcClient

Creates a new instance of MonoCloudOidcClient.

Parameters

Parameter	Type	Description
`tenantDomain`	`string`	The tenant domain URL.
`clientId`	`string`	Client id of the application registered in MonoCloud.
`options?`	`MonoCloudOidcClientOptions`	Additional client configuration options.

Returns

MonoCloudOidcClient

Overrides

MonoCloudOidcClientBase.constructor

Properties

Property	Type	Description
`fetcher?`	{(`input`: `URL` \| `RequestInfo`, `init?`: `RequestInit`): `Promise`<`Response`>; (`input`: `string` \| `URL` \| `Request`, `init?`: `RequestInit`): `Promise`<`Response`>; }	Custom fetch implementation used for making HTTP requests. Falls back to the global `fetch` if not provided.
`jwks?`	`Jwks`	Cached JSON Web Key Set retrieved from the issuer's JWKS endpoint.
`jwksCacheDuration`	`number`	Duration (in seconds) for which the JWKS is cached. Defaults to 300 (5 minutes).
`jwksCacheExpiry`	`number`	Timestamp (in seconds) when the cached JWKS expires.
`metadata?`	`IssuerMetadata`	Cached issuer metadata retrieved from the OpenID Connect discovery endpoint.
`metadataCacheDuration`	`number`	Duration (in seconds) for which the metadata is cached. Defaults to 300 (5 minutes).
`metadataCacheExpiry`	`number`	Timestamp (in seconds) when the cached metadata expires.
`tenantDomain`	`string`	The normalized tenant domain URL used as the base for discovery endpoints.

Methods

authenticate()

authenticate(code: string, redirectUri: string, requestedScopes: string, resource?: string, options?: AuthenticateOptions): Promise<MonoCloudSession>

Generates a session with user and tokens by exchanging authorization code from callback params.

Parameters

Parameter	Type	Description
`code`	`string`	The authorization code received from the callback.
`redirectUri`	`string`	The redirect URI that was used in the authorization request.
`requestedScopes`	`string`	A space-separated list of scopes originally requested via the `/authorize` endpoint. This is stored in the session to ensure the correct access token can be identified and refreshed during `refreshSession()`.
`resource?`	`string`	A space-separated list of resource indicators originally requested via the `/authorize` endpoint. Used alongside scopes to uniquely identify and refresh the specific access token associated with these resources.
`options?`	`AuthenticateOptions`	Options for authenticating a user with authorization code.

Returns

Promise<MonoCloudSession>

The user's session containing authentication tokens and user information.

Throws

MonoCloudValidationError - When the token scope does not contain the openid scope, or if 'expires_in' or 'scope' is missing from the token response.

Throws

MonoCloudOPError - When the OpenID Provider returns a standardized. OAuth 2.0 error response.

Throws

MonoCloudTokenError - If ID Token validation fails.

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

authorizationUrl()

authorizationUrl(params: AuthorizationParams): Promise<string>

Generates an authorization URL with specified parameters.

If no values are provided for responseType, or codeChallengeMethod, they default to code, and S256, respectively.

Parameters

Parameter	Type	Description
`params`	`AuthorizationParams`	Authorization URL parameters.

Returns

Promise<string>

Tenant's authorization URL.

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

decodeJwt()

static decodeJwt(jwt: string): JwtClaims

Decodes the payload of a JSON Web Token (JWT) and returns it as an object.

Note: THIS METHOD DOES NOT VERIFY JWT TOKENS.

Parameters

Parameter	Type	Description
`jwt`	`string`	JWT to decode.

Returns

JwtClaims

Decoded payload.

Throws

MonoCloudTokenError - If decoding fails

Inherited from

MonoCloudOidcClientBase.decodeJwt

endSessionUrl()

endSessionUrl(params: EndSessionParameters): Promise<string>

Generates OpenID end session URL for signing out.

Note - The state is added only when postLogoutRedirectUri is present.

Parameters

Parameter	Type	Description
`params`	`EndSessionParameters`	Parameters to build end session URL.

Returns

Promise<string>

Tenant's end session URL.

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

exchangeAuthorizationCode()

exchangeAuthorizationCode(code: string, redirectUri: string, codeVerifier?: string, resource?: string): Promise<Tokens>

Exchanges an authorization code for tokens.

Parameters

Parameter	Type	Description
`code`	`string`	The authorization code received from the authorization server.
`redirectUri`	`string`	The redirect URI used in the initial authorization request.
`codeVerifier?`	`string`	Code verifier for PKCE.
`resource?`	`string`	Space-separated list of resources the access token should be scoped to.

Returns

Promise<Tokens>

Tokens obtained by exchanging an authorization code at the token endpoint.

Throws

MonoCloudOPError - When the OpenID Provider returns a standardized OAuth 2.0 error response.

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

getJwks()

getJwks(forceRefresh: boolean): Promise<Jwks>

Fetches the JSON Web Keys used to sign the ID token. The JWKS is cached for 5 minutes by default.

Parameters

Parameter	Type	Description
`forceRefresh`	`boolean`	If `true`, bypasses the cache and fetches fresh set of JWKS from the server.

Returns

Promise<Jwks>

The JSON Web Key Set containing the public keys for token verification.

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

Inherited from

MonoCloudOidcClientBase.getJwks

getMetadata()

getMetadata(forceRefresh: boolean): Promise<IssuerMetadata>

Fetches the authorization server metadata from the .well-known endpoint. The metadata is cached for 5 minutes by default.

Parameters

Parameter	Type	Description
`forceRefresh`	`boolean`	If `true`, bypasses the cache and fetches fresh metadata from the server.

Returns

Promise<IssuerMetadata>

The issuer metadata for the tenant, retrieved from the OpenID Connect discovery endpoint.

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

Inherited from

MonoCloudOidcClientBase.getMetadata

pushedAuthorizationRequest()

pushedAuthorizationRequest(params: PushedAuthorizationParams): Promise<ParResponse>

Performs a pushed authorization request.

Parameters

Parameter	Type	Description
`params`	`PushedAuthorizationParams`	Authorization Parameters.

Returns

Promise<ParResponse>

Response from Pushed Authorization Request (PAR) endpoint.

Throws

MonoCloudOPError - When the request is invalid.

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

refetchUserInfo()

refetchUserInfo(accessToken: AccessToken, session: MonoCloudSession, options?: RefetchUserInfoOptions): Promise<MonoCloudSession>

Refetches user information for an existing session using the userinfo endpoint. Updates the session's user object with the latest user information.

Parameters

Parameter	Type	Description
`accessToken`	`AccessToken`	Access token used to fetch the userinfo.
`session`	`MonoCloudSession`	The current MonoCloudSession.
`options?`	`RefetchUserInfoOptions`	Userinfo refetch options.

Returns

Promise<MonoCloudSession>

Updated session with the latest userinfo.

Throws

MonoCloudValidationError - When the token scope does not contain openid scope

Throws

MonoCloudOPError - When the OpenID Provider returns a standardized OAuth 2.0 error response.

Throws

MonoCloudTokenError - If ID Token validation fails

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

refreshGrant()

refreshGrant(refreshToken: string, options?: RefreshGrantOptions): Promise<Tokens>

Exchanges a refresh token for new tokens.

Parameters

Parameter	Type	Description
`refreshToken`	`string`	The refresh token used to request new tokens.
`options?`	`RefreshGrantOptions`	Refresh grant options.

Returns

Promise<Tokens>

Tokens obtained by exchanging a refresh token at the token endpoint.

Throws

MonoCloudOPError - When the OpenID Provider returns a standardized OAuth 2.0 error response.

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

refreshSession()

refreshSession(session: MonoCloudSession, options?: RefreshSessionOptions): Promise<MonoCloudSession>

Refreshes an existing session using the refresh token. This function requests new tokens using the refresh token and optionally updates user information.

Parameters

Parameter	Type	Description
`session`	`MonoCloudSession`	The current MonoCloudSession containing the refresh token.
`options?`	`RefreshSessionOptions`	Session refresh options.

Returns

Promise<MonoCloudSession>

User's session containing refreshed authentication tokens and user information.

Throws

MonoCloudValidationError - If the refresh token is not present in the session, or if 'expires_in' or 'scope' (including the openid scope) is missing from the token response.

Throws

MonoCloudOPError - When the OpenID Provider returns a standardized OAuth 2.0 error response.

Throws

MonoCloudTokenError - If ID Token validation fails

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

revokeToken()

revokeToken(token: string, tokenType?: string): Promise<void>

Revokes an access token or refresh token, rendering it invalid for future use.

Parameters

Parameter	Type	Description
`token`	`string`	The token string to be revoked.
`tokenType?`	`string`	Hint about the token type ('access_token' or 'refresh_token').

Returns

Promise<void>

If token revocation succeeded.

Throws

MonoCloudValidationError - If token is invalid or unsupported token type

Throws

MonoCloudOPError - When the OpenID Provider returns a standardized OAuth 2.0 error response.

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

userinfo()

userinfo(accessToken: string): Promise<UserinfoResponse<Address>>

Fetches userinfo associated with the provided access token.

Parameters

Parameter	Type	Description
`accessToken`	`string`	A valid access token used to retrieve userinfo.

Returns

Promise<UserinfoResponse<Address>>

The authenticated user's claims.

Throws

MonoCloudOPError - When the OpenID Provider returns a standardized OAuth 2.0 error (e.g., 'invalid_token') in the 'WWW-Authenticate' header following a 401 Unauthorized response.

Throws

MonoCloudHttpError - Thrown if there is a network error during the request or unexpected status code during the request or a serialization error while processing the response.

Throws

MonoCloudValidationError - When the access token is invalid.

validateIdToken()

validateIdToken(idToken: string, jwks: Jwk[], clockSkew: number, clockTolerance: number, maxAge?: number, nonce?: string): Promise<IdTokenClaims>

Validates an ID Token.

Parameters

Parameter	Type	Description
`idToken`	`string`	The ID Token JWT string to validate.
`jwks`	`Jwk`[]	Array of JSON Web Keys (JWK) used to verify the token's signature.
`clockSkew`	`number`	Number of seconds to adjust the current time to account for clock differences.
`clockTolerance`	`number`	Additional time tolerance in seconds for time-based claim validation.
`maxAge?`	`number`	Maximum authentication age in seconds.
`nonce?`	`string`	Nonce value to validate against the token's nonce claim.

Returns

Promise<IdTokenClaims>

Validated ID Token claims.

Throws

MonoCloudTokenError - If ID Token validation fails