Refresh tokens
A refresh token is an opaque token that contains the information required to obtain a new access token. A refresh token is long-lived, as opposed to short-lived access tokens and ID tokens.
Refresh tokens can have a validity period, which means that they are revoked upon usage after a certain amount of time.
Note
Ensure that refresh tokens are stored securely and are not leaked. Leaking refresh tokens means that a user account can be compromised.
Issue refresh tokens
A refresh token is an OAuth 2.0-specific token. It is issued as part of the authorization flow.
Issue refresh tokens for web clients
Refresh tokens are only issued when the web client uses the authorization code grant type.
- On the Access admin console, select Configuration > Web clients.
-
Select the web client that you want to update or add a new web client.
-
In the OAuth settings, select the Issue refresh tokens check box.
Issue refresh tokens for mobile applications
YOu can issue refresh tokens as part of a mobile app configuration.
- On the Access admin console, select Configuration > App configuration.
-
Select the application that you want to update, or add a new application.
-
In the User authentication section, select the PIN authentication check box.
Refresh token replay protection
Replay protection enhances refresh token security by revoking all active tokens in a chain if an old refresh token is reused.
The authorization server issues a new refresh token each time an access token is refreshed. The previous refresh token becomes invalid but is still tracked for security purposes. If an old refresh token is reused (either by an attacker or a legitimate client) while the associated access token is still valid, the server recognizes it as a replay attack. Since it cannot determine which party is responsible, the server revokes the currently active refresh token to stop the potential compromise. This breaks the token chain and requires the legitimate client to re-authorize. When such a replay is detected, a RefreshTokenReplayDetectedEvent
is logged to indicate the incident.
If replay protection is explicitly disabled, reuse of an invalidated refresh token does not trigger any revocation.
You can enable replay protection via the Access admin console or programmatically via the API:
-
To enable replay protection on the Access admin console, on the Web Client configuration page, in the OAuth settings, select the Revoke all active refresh tokens when an old refresh token is used check box.
-
To enable replay protection via the Access config and end-user APIs, in the web client configuration, set
revoke_on_refresh_token_replay
totrue
.