Configure Refresh Token Expiration
Refresh tokens can be a target for abuse if leaked because they can be used to acquire new access tokens. To mitigate this risk, Auth0 recommends using Automatic Reuse Detection and Refresh Token Rotation. Refresh Token Rotation issues a refresh token that expires after a preset lifetime. After expiration, the user gets a new refresh token in the same family, or refresh tokens that share a family ID, or a new access token/refresh token pair. To learn more, read Refresh Token Rotation.
You can enable and configure two refresh token lifetime settings, maximum and idle refresh expiration, using either the Auth0 Dashboard or the Auth0 Management API. You can use a combination of maximum and idle refresh expiration periods to create a balance between security and user experience that suits your business needs.
Maximum Lifetime: Set a refresh token or refresh token family lifetime after which the user must re-authenticate before being issued a new access token. If you disable this setting, the maximum lifetime will be indefinite.
Idle Lifetime: Set the idle lifetime of issued refresh tokens to expire if the user is not active in your application during a specified period.
Use the Dashboard
Go to Dashboard > Applications.
Select the application you want to configure.
Go to the Settings tab.
Under Refresh Token Expiration, enable Set Idle Refresh Token Lifetime. When enabled, a refresh token will expire based on the idle refresh token lifetime, after which the token can no longer be used. If rotation is enabled, an expiration lifetime must be set.
The Idle Refresh Token Lifetime of the rotating refresh token is defined on creation and is not changed, even with an exchange.
Enter Idle Refresh Token Lifetime in seconds. The refresh token expires after the specified interval and can no longer be used to get a new access token. When rotation is enabled, the idle refresh token lifetime also applies to the ability to get new tokens.
Lifetime Value Default 2,592,000 seconds (30 days) Minimum 1 second Maximum 31,557,600 seconds (1 year) The calculation for 1 year is equivalent to 365.25 days to account for leap years.
Enable Set Maximum Refresh Token Lifetime. When enabled, a refresh token will expire based on a specified maximum refresh token lifetime, after which the token can no longer be used.
Enter Maximum Refresh Token Lifetime in seconds. If the refresh token is not exchanged within the specified interval, the refresh token expires and can no longer be used to get a new access token. The expiration period is renewed each time the refresh token is exchanged for a new access token within the interval.
Lifetime Value Minimum 1 second Maximum 31,557,600 seconds (1 year) Select Save Changes.
Use the Management API
You can configure the maximum and idle lifetime settings in the payload for the Management API /api/v2/clients/{id} endpoint. Here is an example that sets expiration lifetime for a non-rotating refresh token:
PATCH /api/v2/clients/{id}
{
"refresh_token": {
"rotation_type": "non-rotating",
"expiration_type": "expiring",
"token_lifetime": 2592000,
"infinite_token_lifetime": false,
"idle_token_lifetime": 604800,
"infinite_idle_token_lifetime": false
}
}Was this helpful?
Support and limitations
You can opt-in to use refresh token expiration capabilities; no action is required by you. Existing refresh tokens are not affected.
If need to go above the 1 year limitation (up to 5 years), Auth0 can increase the limit for you. Contact your Auth0 Technical Account Manager for details.
Refresh token expiration works with the following flows:
All Auth0 SDKs support refresh token expiration.
The refresh token expiration feature complies with the OAuth 2.0 Security BCP recommendations.
The OAuth BCP states that refresh tokens issued for browser-based applications must have an expiration and either enforce sender-constraint or rotate tokens with each request. Therefore, SPAs will default into rotation and will not support non-expiring refresh tokens.