Token Refresh Offset Overview

token-refresh-offset-overview.md

Summary

We are moving the token refresh offset from AccessToken to TokenCredential, to keep the originality and correctness of the expiresAt() getter on AccessToken.

On top of refreshing the token at an offset before expiry, we are also allowing the current non-expired token to be used if a proactive refresh fails. The proactive refresh will be attempted again next time some thread needs to get a token. To prevent too many refresh attempts, there will also be a timeout in place.

Current design

Azure/azure-sdk-for-java#11704

Usage

ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
    .clientId("<YOUR_CLIENT_ID>")
    .tokenRefreshOffset(Duration.ofMinutes(5))
    .build();

Default is 2 minutes.

Design key points

• A token credential should have a default method tokenRefreshOptions
• By default, a token credential should have a refresh offset of 2 minutes
• All Azure.Identity credentials should support overriding this offset
• The token should be cached outside the MSAL cache to prevent constant access to the MSAL cache
• Errors should not be thrown if token refresh fails, if the previously cached token is still valid
• Errors should be thrown if token refresh fails, and the previously cache token has expired
• After each refresh, either a success or a failure, another refresh should not be attempted within a configurable timeout, which by default is 30 seconds (check with MSAL)
• Only one thread should be doing token refresh at a moment. Others should use an existing valid token, or wait for this thread to complete