How to Use Refresh Token Rotation in AWS Cognito

Finally, a long-awaited feature of AWS Cognito is here. Now, Cognito user pools support the rotation of refresh tokens. In this post, we’ll understand what has changed and how to implement it in your projects.

What is a Refresh Token? And What Was the Problem?

After successful user authentication, the Cognito user pool returns an ID Token, an Access Token, and a refresh Token. Access Token and ID Token can be utilized to make secure API calls or extract user profile information and are generally short-lived.

To avoid frequent user authentication, Refresh token can be used to retrieve a new ID and Access token. This process can be repeated until the refresh token is valid. Once the refresh token expires, the user needs to go through the login flow again.

Now, the problem with this approach is what should be the validity of the refresh token?

• If the refresh token validity is too short, users are forced to re-authenticate frequently, degrading the user experience.
• If it’s too long, there is a potential security threat ie. compromised Refresh Token could be reused for the entire duration (also known as a replay attack).

The new refresh token rotation feature solves these problems seamlessly.

How AWS Cognito Refresh Token Rotation Works?

After enabling refresh token rotation:-

• Every time a new Access or ID Token is requested using a refresh token (ie. with grant_type=refresh_token), Cognito returns a new refresh token as well.
• The validity of this new refresh token will be the remaining validity of the original refresh token (one that was issued at the time of authentication).
• The previous token becomes invalid (with an optional grace period to allow for retries).

Since the refresh token is rotated (a new one is created and the old one is invalidated) on every /oauth2/token call, the same refresh token can’t be used more than once. This significantly reduces the risk of token replay attacks, allowing developers to safely configure longer Refresh Token lifetimes.

How To Enable Refresh Token Rotation?

• Go to UserPool >> App Clients >> Edit App client information.
• Under Authentication flows, uncheck “ALLOW_REFRESH_TOKEN_AUTH”. Then scroll down to Advanced security configurations and check “Enable token revocation”.

That’s it! Refresh token rotation is successfully enabled and can be used with OAuth2.0 workflow or Cognito SDK. For more details, check out the Cognito Refresh Token Developer Guide.

Refresh Token Rotation With OAuth2.0 Workflow And SDK

1. At the end of the authorization_code grant_type OAuth2.0 workflow, the code received can be used to get tokens.
2. After the expiry of the Access Token, use the Refresh Token to get new tokens.

curl -X POST \
  https://<USERPOOL_DOMAIN_HERE>/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&client_id=<CLIENT_ID_HERE>&code=<AUTHORIZATION_CODE_HERE>&redirect_uri=<REDIRECT_URI_HERE>'

curl -X POST \
  https://<USERPOOL_DOMAIN_HERE>/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id=<CLIENT_ID_HERE>&refresh_token=<REFRESH_TOKEN>'

Similarly, for SDK, GetTokensFromRefreshTokenCommand can be used.

import { CognitoIdentityProviderClient, GetTokensFromRefreshTokenCommand } from "@aws-sdk/client-cognito-identity-provider"; 

const config = {
  region: "ap-south-1"
}

const client = new CognitoIdentityProviderClient(config);
const input = { // GetTokensFromRefreshTokenRequest
  RefreshToken: "STRING_VALUE", // required
  ClientId: "STRING_VALUE", // required
  ClientSecret: "STRING_VALUE",
};

const command = new GetTokensFromRefreshTokenCommand(input);
const response = await client.send(command);

console.log(response); 

Thanks ☺️