Identity Gateway 2024.3

Access token resolvers

The following objects are available to resolve OAuth 2.0 access tokens:

TokenIntrospectionAccessTokenResolver

In OAuth2ResourceServerFilter, use the token introspection endpoint, /oauth2/introspect, to resolve access tokens and retrieve metadata about the token. The endpoint typically returns the time until the token expires, the OAuth 2.0 scopes associated with the token, and potentially other information.

The introspection endpoint is defined as a standard method for resolving access tokens, in RFC-7662, OAuth 2.0 Token Introspection.

Usage

Use this resolver with the accessTokenResolver property of OAuth2ResourceServerFilter.

"accessTokenResolver": {
  "type": "TokenIntrospectionAccessTokenResolver",
  "config": {
    "amService": AmService reference,          // Use either "amService"
    "endpoint": configuration expression<url>, // or "endpoint", but not both.
    "providerHandler": Handler reference
  }
}

Properties

"amService": AmService reference, required if endpoint is not configured

The AmService heap object to use for the token introspection endpoint. The endpoint is extrapolated from the url property of the AmService.

When the Authorization Server is AM, use this property to define the token introspection endpoint.

If amService is configured, it takes precedence over endpoint.

See also AmService.

"endpoint": configuration expression<url>, required if amService is not configured

The URI for the token introspection endpoint. Use /oauth2/introspect.

When the Authorization Server is not AM, use this property to define the token introspection endpoint.

If amService is configured, it takes precedence over endpoint.

"providerHandler": Handler reference, optional

Invoke this HTTP client handler to send token info requests.

Provide either the name of a Handler object defined in the heap or an inline Handler configuration object.

Default: ForgeRockClientHandler

If you use the AM token introspection endpoint, this handler can be a Chain containing a HeaderFilter to add the authorization to the request header, as in the following example:

"providerHandler": {
  "type": "Chain",
  "config": {
    "filters": [
      {
        "type": "HeaderFilter",
        "config": {
          "messageType": "request",
          "add": {
            "Authorization": [ "Basic ${encodeBase64('<client_id>:<client_secret>')}" ]
          }
        }
      }
    ],
    "handler": "ForgeRockClientHandler"
  }
}

Example

For an example route that uses the token introspection endpoint, refer to Validate access tokens through the introspection endpoint.

More information

org.forgerock.openig.filter.oauth2.TokenIntrospectionAccessTokenResolverHeaplet

OAuth2ResourceServerFilter

StatelessAccessTokenResolver

Locally resolve and validate stateless access tokens issued by AM, without referring to AM.

AM can be configured to secure access tokens by signing or encrypting. The StatelessAccessTokenResolver must be configured for signature or encryption according to the AM configuration.

Usage

Use this resolver with the accessTokenResolver property of OAuth2ResourceServerFilter.

"accessTokenResolver": {
  "type": "StatelessAccessTokenResolver",
  "config": {
    "issuer": configuration expression<string>,
    "secretsProvider": SecretsProvider reference,
    "verificationSecretId": configuration expression<secret-id>, // Use "verificationSecretId" or
    "decryptionSecretId": configuration expression<secret-id>,   // "decryptionSecretId", but not both
    "skewAllowance": configuration expression<duration>
  }
}

Properties

"issuer": configuration expression<string>, required

URI of the AM instance responsible for issuing access tokens.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for passwords and cryptographic keys.

"verificationSecretId": configuration expression<secret-id>, required if AM secures access tokens with a signature

The secret ID for the secret used to verify the signature of signed access tokens.

This secret ID must point to a CryptoKey.

Depending on the type of secret store that is used to verify signatures, use the following values:

  • For JwkSetSecretStore, use any non-empty string that conforms to the field convention for secret-id. The value of the string is not used.

  • For other types of secret stores:

    • null: No signature verification is required.

    • A kid as a string: Signature verification is required with the provided kid. The StatelessAccessTokenResolver searches for the matching kid in the SecretsProvider.

For information about how signatures are validated, refer to Validate the signature of signed tokens. For information about how each type of secret store resolves named secrets, refer to Secrets.

Use either verificationSecretId or decryptionSecretId, according to the configuration of the token provider in AM. If AM is configured to sign and encrypt tokens, encryption takes precedence over signing.

"decryptionSecretId": configuration expression<secret-id>, required if AM secures access tokens with encryption

The secret ID for the secret used to decrypt the JWT, for confidentiality.

This secret ID must point to a CryptoKey.

Use either verificationSecretId or decryptionSecretId, according to the configuration of the token provider in AM. If AM is configured to sign and encrypt the token, encryption takes precedence over signing.

"skewAllowance": configuration expression<duration>, optional

The duration to add to the validity period of a JWT to allow for clock skew between different servers.

A skewAllowance of 2 minutes affects the validity period as follows:

  • A JWT with an iat of 12:00 is valid from 11:58 on the IG clock.

  • A JWT with an exp 13:00 is expired after 13:02 on the IG clock.

Default: To support a zero-trust policy, the skew allowance is by default zero.

Example

For examples of how to set up and use StatelessAccessTokenResolver to resolve signed and encrypted access tokens, refer to Validate stateless access tokens with the StatelessAccessTokenResolver.

More information

org.forgerock.openig.filter.oauth2.StatelessAccessTokenResolver

OAuth2ResourceServerFilter

ConfirmationKeyVerifierAccessTokenResolver

In OAuth2ResourceServerFilter, use the ConfirmationKeyVerifierAccessTokenResolver to verify that certificate-bound OAuth 2.0 bearer tokens presented by clients use the same mTLS-authenticated HTTP connection.

When a client obtains an access token from AM by using mTLS, AM can optionally use a confirmation key to bind the access token to a certificate. When the client connects to IG using that certificate, the ConfirmationKeyVerifierAccessTokenResolver verifies that the confirmation key corresponds to the certificate.

This proof-of-possession interaction ensures that only the client in possession of the key corresponding to the certificate can use the access token to access protected resources.

To use the ConfirmationKeyVerifierAccessTokenResolver, the following configuration is required in AM:

  • OAuth 2.0 clients must be registered using an X.509 certificate, that is self-signed or signed in public key infrastructure (PKI)

  • The AM client authentication method must be self_signed_client_auth or tls_client_auth.

  • AM must be configured to bind a confirmation key to each client certificate.

The ConfirmationKeyVerifierAccessTokenResolver delegates the token resolution to a specified AccessTokenResolver, which retrieves the token information. The ConfirmationKeyVerifierAccessTokenResolver verifies the confirmation keys bound to the access token, and then acts as follows:

  • If there is no confirmation key, pass the request down the chain.

  • If the confirmation key matches the client certificate, pass the request down the chain.

  • If the confirmation key doesn’t match the client certificate, throw an error.

  • If the confirmation key method is not supported by IG, throw an error.

For an example that uses the ConfirmationKeyVerifierAccessTokenResolver, refer to Validate Certificate-Bound Access Tokens.

For information about issuing certificate-bound OAuth 2.0 access tokens, refer to Certificate-bound proof-of-possession in AM’s OAuth 2.0 guide. For information about authenticating an OAuth 2.0 client using mTLS certificates, refer to Mutual TLS in AM’s OAuth 2.0 guide .

Usage

Use this resolver with the accessTokenResolver property of OAuth2ResourceServerFilter.

"accessTokenResolver": {
  "type": "ConfirmationKeyVerifierAccessTokenResolver",
  "config": {
    "delegate": AccessTokenResolver reference
  }
}

Properties

"delegate": AccessTokenResolver reference, required

The access token resolver to use for resolving access tokens. Use any access token resolver described in Access token resolvers.

Examples

For an example that uses the ConfirmationKeyVerifierAccessTokenResolver with the following route, refer to Validate Certificate-Bound Access Tokens.

More information

org.forgerock.openig.filter.oauth2.cnf.ConfirmationKeyVerifierAccessTokenResolver

OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens

OAuth2ResourceServerFilter

ScriptableAccessTokenResolver

In OAuth2ResourceServerFilter, use a Groovy script to resolve access tokens against an Authorization Server.

Receive a string representing an access token and use a Groovy script to create an instance or promise of org.forgerock.http.oauth2.AccessTokenInfo.

Usage

Use this resolver with the accessTokenResolver property of OAuth2ResourceServerFilter.

"accessTokenResolver": {
  "type": "ScriptableAccessTokenResolver",
  "config": {
    "type": configuration expression<string>,
    "file": configuration expression<string>,  // Use either "file"
    "source": [ string, ... ],                 // or "source", but not both.
    "args": map,
    "clientHandler": Handler reference
  }
}

Properties

For information about properties for ScriptableAccessTokenResolver, refer to Scripts.

More information

org.forgerock.openig.filter.oauth2.ScriptableAccessTokenResolver

OAuth2ResourceServerFilter

CacheAccessTokenResolver

Enable and configure caching of OAuth 2.0 access tokens, based on Caffeine. For more information, refer to the GitHub entry, Caffeine.

This resolver configures caching of OAuth 2.0 access tokens, and delegates their resolution to another AccessTokenResolver. Use this resolver with AM or any OAuth 2.0 access token provider.

For an alternative way to cache OAuth 2.0 access tokens, configure the cache property of OAuth2ResourceServerFilter.

Usage

{
  "name": string,
  "type": "CacheAccessTokenResolver",
  "config": {
    "delegate": AccessTokenResolver reference,
    "enabled": configuration expression<boolean>,
    "defaultTimeout": configuration expression<duration>,
    "executor": Executor reference,
    "maximumSize": configuration expression<number>,
    "maximumTimeToCache": configuration expression<duration>,
    "amService": AmService reference,
    "onNotificationDisconnection": configuration expression<enumeration>
  }
}

Properties

"delegate": AccessTokenResolver reference, required

Delegate access token resolution to one of the access token resolvers in Access token resolvers.

To use AM WebSocket notification to evict revoked access tokens from the cache, the delegate must be able to provide the token metadata required to update the cache.

  • The notification property of AmService is enabled.

  • The delegate AccessTokenResolver provides the token metadata required to update the cache.

enabled: configuration expression<boolean>, optional

Enable caching.

When an access token is cached, IG can reuse the token information without repeatedly asking the Authorization Server to verify the access token. When caching is disabled, IG must ask the Authorization Server to validate the access token for each request.

Default: true

defaultTimeout: configuration expression<duration>, optional

The duration for which to cache an OAuth 2.0 access token when it doesn’t provide a valid expiry value or maximumTimeToCache.

If the defaultTimeout is longer than the maximumTimeToCache, then the maximumTimeToCache takes precedence.

Default: 1 minute

"executor": Executor reference, optional

An executor service to schedule the execution of tasks, such as the eviction of entries from the cache.

Default: ForkJoinPool.commonPool()

"maximumSize": configuration expression<number>, optional

The maximum number of entries the cache can contain.

Default: Unlimited/unbound

"maximumTimeToCache": configuration expression<duration>, optional

The maximum duration for which to cache access tokens.

Cached access tokens are expired according to their expiry time and maximumTimeToCache, as follows:

  • If the expiry time is before the current time plus the maximumTimeToCache, the cached token is expired when the expiry time is reached.

  • If the expiry time is after the current time plus the maximumTimeToCache, the cached token is expired when the maximumTimeToCache is reached

    The duration cannot be zero or unlimited.

Default: The token expiry time or defaultTimeout

"amService": AmService reference, optional

An AmService to use for the WebSocket notification service.

When an access token is revoked on AM, the CacheAccessTokenResolver can delete the token from the cache when both of the following conditions are true:

  • The notification property of AmService is enabled.

  • The delegate AccessTokenResolver provides the token metadata required to update the cache.

    When a refresh_token is revoked on AM, all associated access tokens are automatically and immediately revoked.

See also AmService.

onNotificationDisconnection: configuration expression<enumeration>, optional

An amService must be configured for this property to have effect.

The strategy to manage the cache when the WebSocket notification service is disconnected, and IG receives no notifications for AM events. If the cache is not cleared it can become outdated, and IG can allow requests on revoked sessions or tokens.

Cached entries that expire naturally while the notification service is disconnected are removed from the cache.

Use one of the following values:

  • NEVER_CLEAR

    • When the notification service is disconnected:

      • Continue to use the existing cache.

      • Deny access for requests that are not cached, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Continue to use the existing cache.

      • Query AM for incoming requests that are not found in the cache, and update the cache with these requests.

  • CLEAR_ON_DISCONNECT

    • When the notification service is disconnected:

      • Clear the cache.

      • Deny access to all requests, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

      • Update the cache with these requests.

  • CLEAR_ON_RECONNECT

    • When the notification service is disconnected:

      • Continue to use the existing cache.

      • Deny access for requests that are not cached, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

      • Update the cache with these requests.

Default: CLEAR_ON_DISCONNECT

Example

For an example that uses the CacheAccessTokenResolver, refer to Cache access tokens.