What is refresh token rotation and why is it important?

What is refresh token?#

Refresh token is a special type of token that is used to obtain a new access token when the current access token expires. Check out our previous post Understanding tokens in OIDC to learn more.

During the introduction, we also mentioned that in Logto, in order to protect your refresh token safety, we have enforced a “refresh token rotation” mechanism by default.

But what exactly is “refresh token rotation”? How does it benefit our end users? Let’s dive in!

What is refresh token rotation?#

Refresh token rotation is a mechanism that invalidates the previous refresh token and issues a new one when the refresh token is used to obtain a new access token. This mechanism ensures that the refresh token is renewed before it expires.

Why do we need refresh token rotation?#

Refresh tokens have prolonged lifetime span, usually in weeks or even months. And since we can obtain new access tokens by refresh token, the refresh token becomes an attractive target for attackers as well. Therefore, according to OAuth 2.0 BCP, the authorization server must take one of the following measures to prevent such attacks.

• Issuing sender-constrained refresh tokens: the client signs and provide a signature (Sec-Token-Binding) in the refresh request header, so the issued refresh token is cryptographically bound to a specific client. However, only some of the native clients are sender-constrained nowadays, and most of the modern SPAs and mobile clients are public.
• Refresh token rotation: the authorization server issues a new refresh token (typically when exchanging for a new access token) and invalidate the previous one. This mitigates the risk of a token leakage.

Best practices for implementing refresh token rotation#

In Logto, when a user is successfully signed in, a Grant object will be created first in DB and the subsequently issued refresh token will have a reference grantId and points to the very first Grant object.

Whenever a refresh token rotation occurs, the previous refresh token will be marked as consumed, and the Logto authorization server will issue a new refresh token with the same grantId.

Let’s assume the previous refresh token is leaked, then either the legitimate client or the attacker would have used it to exchange an access token. And no matter who did that, the leaked refresh token must have been rotated and marked as consumed already. One of them who used the consumed refresh token secondly will inform the authorization server of the breach. The authorization server will all refresh tokens with the same grantId will be revoked.

In the case above, after triggering the alarm, the legitimate client can only re-authenticate through sign-in flow again in order to obtain a new refresh token. The attacker, on the other hand, will lose the control of your system and be blocked outside.

When does refresh token rotation happen?#

In Logto, the default behavior of a refresh token rotation defines:

• If the client is sender-constrained or non-public (e.g. server-side rendering web applications), then the refresh token rotation happens when it reaches 70% of its total time-to-live (TTL).
• If the client is a public client (e.g. single-page web applications), the refresh token rotation happens every time it is used to exchange for an access token. The token exchange response will return both a new access token and a new refresh token.

How can I enable/disable refresh token rotation in Logto?#

In Logto admin console, go to Admin Console > Applications and select the application you would like to toggle refresh token rotation. In the application details page, go to the “Advanced settings” tab, and scroll down to the bottom, you will find the switch along with some other useful settings.

If you turn off the switch, your refresh token will never be rotated until it expires. Thereby, we strongly recommend to always enable refresh token rotation.

Recap: What is refresh token rotation and why is it important?#

Refresh token rotation is a best practice that ensures refresh token safety in your application. It invalidates the previous refresh token and issues a new one when the refresh token is used to obtain a new access token. This mechanism mitigates the risk of a token leakage and ensures the safety of your refresh token.

Logto follows industry leading best practices and always put user safety as the top priority.

I hope this blog explains well your doubts about refresh token rotation mechanism. Let us know if there is still something unclear. Your feedback and suggestions are always welcome!

Try Logto today and embrace a safer authentication experience.