Understanding refresh token rotation
Introduction:
Last week, we have talked about the key aspects of OIDC tokens, and learned the roles and attributes of the refresh token, access token and ID token. Refresh token is a convenient way to obtain new access tokens upon the expiration of older ones, and enables the access token with a short lifetime span.
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!
Protect your refresh tokens:
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.
How does Logto implement 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, 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 app), 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 “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.
Closing notes
Refresh token rotation is a best practice that ensures refresh token safety in your application. 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.