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, there are two problems with this approach:-

• Even if a user is active, they are logged out after the expiry of the refresh token. One way is to keep a longer refresh token lifetime. But the question comes how long? Also, keeping it too long is a potential security threat in case of a compromised refresh token.
• The same refresh token can be reused multiple times.

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/ID Token is requested using a refresh token (ie. with grant_type=refresh_token), Cognito now returns a new refresh token as well. Now if a user is active, fresh tokens can be fetched for a long time without compromising security. It works like a sliding window.
• A new refresh token is returned on every /oauth2/token call and the old one becomes invalid (with optional grace time). So the problem of using the same refresh_token is also resolved.

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 ☺️