Skip to main content

Graceful refresh token rotation

Graceful refresh token rotation is a feature in Ory OAuth2 and Ory Hydra that allows for a smoother transition during refresh token usage. With this feature enabled, a refresh token remains valid within a defined grace period, allowing multiple usages without immediate invalidation. This can be beneficial in scenarios where network issues or delayed token exchanges may otherwise disrupt session continuity.

When enabled, using a refresh token marks it as "used" in the database and increments the "usage counter" for that token. Further, the token's expiration time is increased by the duration of the configured grace period. As long as the grace period is active and the reuse counter does not exceed the configured limit, subsequent token refreshes will return new access and refresh tokens. All tokens issued in this grace period remain linked in a single token chain, so revoking one refresh token or consent will invalidate all associated tokens.

Limiting refresh token reuse​

By default, a refresh token can be reused unlimited times within the grace period. To further restrict how often a refresh token can be reused during the grace period, you can set the rotation_grace_reuse_count option. This is especially recommended when you want a longer grace period, as this minimizes the security concerns associated with the graceful token refresh.

  • If rotation_grace_reuse_count is set to a positive integer - for example 3 - a refresh token can only be reused up to that many times - in this example 3 times - within the grace period. After the limit is reached further attempts to use the token will be rejected.
  • By default the rotation_grace_reuse_count is set to 0 and there is no limit on the number of refreshes within the grace period.

Enable graceful refresh token rotation​

To enable graceful refresh token rotation with a specific grace period and a maximum reuse count, for example 60 seconds and 3 reuses, run the following command:

ory patch oauth2-config --project <project-id> --workspace <workspace-id> \
  --replace '/oauth2/grant/refresh_token/rotation_grace_period="60s"' \
  --replace '/oauth2/grant/refresh_token/rotation_grace_reuse_count=3'

In this command:

  • <project-id> and <workspace-id> should be replaced with your specific project and workspace identifiers.
  • The rotation_grace_period specifies the grace period duration. Here, 60s sets a 60-second grace period.
  • The rotation_grace_reuse_count sets the maximum number of times a refresh token can be reused within the grace period. Here, 3 allows up to three reuses.
info

The grace period cannot exceed 5 minutes unless a count limit is also configured.

Disable graceful refresh token rotation​

To disable the graceful refresh token rotation, remove the rotation_grace_period and/or rotation_grace_reuse_count parameter using the command below:

ory patch oauth2-config --project <project-id> --workspace <workspace-id> \
  --remove "/oauth2/grant/refresh_token/rotation_grace_period" \
  --remove "/oauth2/grant/refresh_token/rotation_grace_reuse_count"

Configuration in self-hosted deployments​

For self-hosted Ory deployments, you can configure graceful refresh token rotation in your configuration file:

oauth2:
  grant:
    refresh_token:
      rotation_grace_period: 60s # Set grace period. Omit this line to disable.
      rotation_grace_reuse_count: 3 # Set maximum number of reuses within the grace period. Set to 0 for unlimited.

If rotation_grace_period is set to a positive duration, the refresh token remains valid within this period, providing clients with new tokens for each request without immediate invalidation of the original token. If rotation_grace_reuse_count is set to a positive integer, the number of refreshes within the grace period is limited to that value. If set to 0, the number of refreshes is unlimited within the grace period.

Example behavior with grace period and reuse count​

When the user calls /oauth2/auth and performs login and consent, the OAuth2 server issues an access token and a refresh token. These tokens and all subsequent tokens issued within the grace period are part of the same consent request.

  • Using the refresh token within the grace period: If a refresh token is used multiple times within the configured grace period - for example 60 seconds- each usage results in a new set of access and refresh tokens.
  • Revocation implications: Any refresh token issued within the grace period is part of the same consent request. Revoking one token, or when the user revokes their consent, all tokens belonging to the original consent request, including those issued through a graceful refresh, are invalidated.
  • Re-use detection: If a refresh token is used, and then used again after the grace period ends or used more often than the configured count within the grace period, re-use detection will revoke all tokens linked to the consent request.
  • Token rotation: When a refresh token is used, the access token it was issued with will be revoked. Other access tokens will not be revoked unless one of the above conditions is met. This prevents cases where two competing clients are invalidating one other's tokens.

Use cases for graceful refresh token rotation​

Graceful refresh token rotation can be useful for

  • high-availability applications where token exchange delays could interrupt user experience.
  • distributed systems with multiple servers handling refresh tokens, minimizing the risk of accidental token invalidation.
  • single-page applications, where network connectivity or token exchange delays may cause token rotation issues.
  • mobile applications, where network connectivity can delay refresh token exchange, risking session continuity.