Class AccessTokenCache

java.lang.Object
com.azure.core.credential.AccessTokenCache
public final class AccessTokenCache extends Object

AccessTokenCache is a thread-safe token cache that wraps a TokenCredential and manages proactive token refresh. It supports both asynchronous and synchronous token retrieval via getToken(TokenRequestContext, boolean) and getTokenSync(TokenRequestContext, boolean).

The cache maintains a single cached AccessToken per instance and proactively refreshes it before expiry (by default 5 minutes before the expiry time, or at the refreshAt time if provided by the credential). If a refresh fails while a non-expired token is still available, the cached token continues to be returned until it expires.

When the refreshOnContextChange flag is true, the cache compares the incoming TokenRequestContext (scopes, tenant ID, claims) against the context used to acquire the current cached token. A mismatch causes an immediate token refresh regardless of expiry. This is the mechanism used to support Continuous Access Evaluation (CAE) claims challenges.

Note: Each instance caches exactly one AccessToken associated with one TokenRequestContext. Do not share a single AccessTokenCache instance across calls that require different scopes or tenants simultaneously, as each new context will evict the previously cached token.

This class is thread-safe. Multiple threads may call getToken(TokenRequestContext, boolean) and getTokenSync(TokenRequestContext, boolean) concurrently.

Sample: Wrapping a TokenCredential with AccessTokenCache 

TokenCredential credential = new BasicAuthenticationCredential("username", "password");
AccessTokenCache tokenCache = new AccessTokenCache(credential);
TokenRequestContext requestContext = new TokenRequestContext().addScopes("https://management.azure.com/.default");
// Async usage
Mono<AccessToken> tokenMono = tokenCache.getToken(requestContext, false);
// Sync usage
AccessToken token = tokenCache.getTokenSync(requestContext, false);
See Also:

  • Constructor Details

    • AccessTokenCache

      public AccessTokenCache(TokenCredential tokenCredential)
      Creates an instance of AccessTokenCache that wraps the given TokenCredential.
      Parameters:
      tokenCredential - the token credential to be used to acquire the token.

  • Method Details

    • getToken

      public Mono<AccessToken> getToken(TokenRequestContext tokenRequestContext, boolean refreshOnContextChange)
      Asynchronously get a token from either the cache or replenish the cache with a new token.
      Parameters:
      tokenRequestContext - The request context for token acquisition.
      refreshOnContextChange - When true, compares the incoming TokenRequestContext against the one used to acquire the current cached token. If the scopes, tenant ID, or claims differ, a fresh token is fetched immediately regardless of expiry. Pass false to always use the cached token when it is still valid.
      Returns:
      a Mono that emits the cached or newly acquired AccessToken.
      Throws:
      IllegalArgumentException - if tokenRequestContext is null.

    • getTokenSync

      public AccessToken getTokenSync(TokenRequestContext tokenRequestContext, boolean refreshOnContextChange)
      Synchronously get a token from either the cache or replenish the cache with a new token.
      Parameters:
      tokenRequestContext - The request context for token acquisition.
      refreshOnContextChange - When true, compares the incoming TokenRequestContext against the one used to acquire the current cached token. If the scopes, tenant ID, or claims differ, a fresh token is fetched immediately regardless of expiry. Pass false to always use the cached token when it is still valid.
      Returns:
      the cached or newly acquired AccessToken.
      Throws:
      IllegalArgumentException - if tokenRequestContext is null.