Backend client for validating access tokens in Node.js server applications.
Extends the core OIDC backend client with caching support and automatic detection of JWT vs. opaque token formats.
protectedclockSkew:number=0
Number of seconds to adjust the current time to account for clock differences between the client and server during time-based claim validation. Defaults to 0.
protectedclockTolerance:number=300
Additional time tolerance in seconds applied when validating time-based claims (exp, nbf). Defaults to 300 (5 minutes).
new MonoCloudBackendNodeClient(options?:Partial<MonoCloudBackendNodeClientOptions>):MonoCloudBackendNodeClient
Creates a new instance of MonoCloudBackendNodeClient.
| Parameter | Type | Description |
|---|---|---|
options? | Partial<MonoCloudBackendNodeClientOptions> | Client configuration options. When omitted, configuration is read from environment variables. |
Decodes the payload of a JSON Web Token (JWT) and returns it as an object.
Note: THIS METHOD DOES NOT VERIFY JWT TOKENS.
| Parameter | Type | Description |
|---|---|---|
jwt | string | JWT to decode. |
MonoCloudTokenError - If decoding fails
protectedoptionalfetcher: {(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.
(input:URL|RequestInfo,init?:RequestInit):Promise<Response>
| Parameter | Type |
|---|---|
input | URL | RequestInfo |
init? | RequestInit |
Promise<Response>
(input:string|URL|Request,init?:RequestInit):Promise<Response>
| Parameter | Type |
|---|---|
input | string | URL | Request |
init? | RequestInit |
Promise<Response>
Fetches the JSON Web Keys used to sign the ID token. The JWKS is cached for 5 minutes by default.
| Parameter | Type | Description |
|---|---|---|
forceRefresh | boolean | If true, bypasses the cache and fetches fresh set of JWKS from the server. |
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.
Fetches the authorization server metadata from the .well-known endpoint. The metadata is cached for 5 minutes by default.
| Parameter | Type | Description |
|---|---|---|
forceRefresh | boolean | If true, bypasses the cache and fetches fresh metadata from the server. |
Promise<IssuerMetadata>
The issuer metadata for the tenant, retrieved from the OpenID Connect discovery endpoint.
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.
Validates an opaque access token using the OAuth 2.0 Token Introspection endpoint (RFC 7662).
| Parameter | Type | Description |
|---|---|---|
accessToken | string | The access token string to introspect. |
options? | IntrospectOptions | Claims validation options. |
MonoCloudTokenError - If the token is not active or claim validation fails.
MonoCloudOPError - When the introspection endpoint returns a standardized OAuth 2.0 error response.
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.
MonoCloudValidationError - When the access token is empty or the introspection endpoint is not available in the issuer metadata or claims validation fails.
Cached JSON Web Key Set retrieved from the issuer's JWKS endpoint.
protectedjwksCacheDuration:number=300
Duration (in seconds) for which the JWKS is cached. Defaults to 300 (5 minutes).
protectedjwksCacheExpiry:number=0
Timestamp (in seconds) when the cached JWKS expires.
Cached issuer metadata retrieved from the OpenID Connect discovery endpoint.
protectedmetadataCacheDuration:number=300
Duration (in seconds) for which the metadata is cached. Defaults to 300 (5 minutes).
protectedmetadataCacheExpiry:number=0
Timestamp (in seconds) when the cached metadata expires.
setClockSkew(clockSkew:number):void
Sets clock skew used for access token time-based claim validation.
| Parameter | Type | Description |
|---|---|---|
clockSkew | number | Number of seconds to adjust the current time to account for clock differences. |
void
setClockTolerance(clockTolerance:number):void
Sets clock tolerance used for access token time-based claim validation.
| Parameter | Type | Description |
|---|---|---|
clockTolerance | number | Additional time tolerance in seconds for time-based claim validation. |
void
protectedreadonlytenantDomain:string
The normalized tenant domain URL used as the base for discovery endpoints.
validateAccessToken(accessToken:string,options?:ValidateAccessTokenOptions):Promise<AccessTokenClaims>
Validates an access token by automatically detecting its format.
| Parameter | Type | Description |
|---|---|---|
accessToken | string | The access token string to validate. |
options? | ValidateAccessTokenOptions | Validation options. |
MonoCloudValidationError - When the access token is empty.
MonoCloudTokenError - If token validation fails.
MonoCloudOPError - When the introspection endpoint returns a standardized OAuth 2.0 error response.
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.
validateJwtAccessToken(accessToken:string,options?:ValidateJwtAccessTokenOptions):Promise<AccessTokenClaims>
Validates a JWT access token by verifying the signature and claims.
| Parameter | Type | Description |
|---|---|---|
accessToken | string | The access token JWT string to validate. |
options? | ValidateJwtAccessTokenOptions | Validation options. |
MonoCloudTokenError - If JWT parsing, signature verification, or claim validation fails.
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.
MonoCloudValidationError - When the access token is empty or claims validation fails.