How do I revoke refresh tokens issued by Amazon Cognito?

Resolution

You can use APIs and endpoints to revoke refresh tokens generated by Amazon Cognito.

Note: You can revoke refresh tokens in real time so that these refresh tokens can't generate access tokens.

Prerequisites for revoking refresh tokens

Turn on token revocation for an app client to revoke the refresh tokens issued by that app client. The EnableTokenRevocation parameter is turned on by default when you create a new Amazon Cognito user pool client. Before you can revoke a token for an existing user pool client, turn on token revocation within the UpdateUserPoolClient API operation. Include the current settings from your app client and set the EnableTokenRevocation parameter to true.

When you turn on token revocation settings, the origin_jti and jti claims are added to the access and ID tokens.

• The jti claim provides a unique identifier for JSON Web Tokens (JWTs).
• The jti claim is used to prevent the JWTs from being replayed.
• The jti value is a case-sensitive string.
• When the REFRESH_TOKEN authentication flow is used to generate new access and ID tokens, the new access and ID tokens have the same origin_jti claim. The jti claims are different.

For more information, see Turn on token revocation and Using tokens with user pools.

Expected results of revoking refresh tokens

For information about what to expect when you revoke refresh tokens, including the effect on access tokens and JWTs, see Revoking tokens and RevokeToken.

Note: For more information about JWTs, see Verifying a JSON Web Token.

Using the RevokeToken API call to revoke refresh tokens

The refresh token to be revoked, the app client ID, and the client secret are required parameters to call the RevokeToken API.

Note: The client secret is required only when the client ID has a secret.

Request syntax:

{
  "ClientId": "string",
  "ClientSecret": "string",
  "Token": "string"
}

Example AWS Command Line Interface (AWS CLI) command:

Note: Replace the token <value> with your token information. Replace the client-id <value> with your client ID. Replace the client-secret <value> with your app client's secret.

aws cognito-idp revoke-token
--token <value>
--client-id <value>
--client-secret <value>

Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent version of the AWS CLI.

Example curl command:

Note: Replace <region> with your AWS Region. Replace <refresh token> with your token information. Replace <client-id> with your client ID.

awscurl \
-v \
-X POST \
--service cognito-idp \
--region <region> \
-H 'X-Amz-Target: AWSCognitoIdentityProviderService.RevokeToken' \
-H 'Content-Type: application/x-amz-json-1.1' \
-d '{"ClientId": "<client-id>", "Token": "<refresh-token>"}' \
https://cognito-idp.<region>.amazonaws.com

Using the revoke endpoint to revoke refresh tokens

The /oauth2/revoke endpoint is available after you add a domain to your user pool. After the endpoint revokes the tokens, you can't use the revoked tokens to access the APIs that Amazon Cognito tokens authenticate. For information about the /oauth2/revoke endpoint, including request parameters, see Revoke endpoint.

Example 1: Revoke token with an app client with no app secret:

Note: Replace <region> with your AWS Region. Replace <refresh token> with your refresh token information. Replace <client-id> with your client ID.

POST /oauth2/revoke HTTP/1.2
    Host: https://mydomain.auth.<region>.amazoncognito.com
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded
    token=<refresh token>&
    client_id=<client-id>

Example 2: Revoke token with an app client with app secret:

POST /oauth2/revoke HTTP/1.2
    Host: https://mydomain.auth.<region>.amazoncognito.com
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded
    Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
    token=<refresh token>

To learn about setting up an authorization header, see How do I troubleshoot "Unable to verify secret hash for client <client-id>" errors from my user pool?

Endpoint errors

For more information about endpoint errors, see Revoke endpoint and review the information under Revocation error response.