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 extends its expiration time by the duration of the configured grace period. As long as the grace period is active, 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.

Enable graceful refresh token rotation

To enable graceful refresh token rotation with a specific grace period, for example 60 seconds, run the following command:

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

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.

Disable graceful refresh token rotation

To disable the graceful refresh token rotation, remove the rotation_grace_period parameter using the command below:

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

Configuration in self-hosted deployments

For self-hosted deployments with Ory Enterprise License or Ory OSS, 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.

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.

Example behavior with grace period

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 twice 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, 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.

The grace period cannot exceed 5 minutes.

Use cases for graceful refresh token rotation

Graceful refresh token rotation can be particularly useful in:

• 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 intermittent network connectivity can delay refresh token exchange, risking session continuity.

Enabling this feature helps ensure smoother token lifecycle management while maintaining secure and efficient token rotation behavior.