PingGateway 2024.9

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, PingGateway can reuse the token information without repeatedly asking the Authorization Server to verify the access token. When caching is disabled, PingGateway 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 PingGateway receives no notifications for AM events. If the cache is not cleared it can become outdated, and PingGateway 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.