How do I revoke JWT tokens in Amazon Cognito using the AWS CLI?

4 minute read

I want to revoke JSON Web Tokens (JWTs) tokens that are issued in an Amazon Cognito user pool.

Short description

Amazon Cognito refresh tokens expire 30 days after a user signs in to a user pool. You can set the app client refresh token expiration between 60 minutes and 10 years. For more information, see Using the refresh token.

You can also revoke refresh tokens in real time. This makes sure that refresh tokens can't generate additional access tokens. All previously issued access tokens by the refresh token aren't valid.

When you revoke refresh tokens, this has no effect on other refresh tokens that are associated with parallel user sessions.

Resolution

To revoke a JWT token, refer to the relevant instructions based on your app client.

Note:

If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.
Amazon Cognito user pool app clients can have an optional secret for the app. For more information, see Configuring a user pool app client.
Replace us-east-1 with your AWS Region, and user-pool-id, client-id, username, email, tokens, secret, and password with your variables.

App client without a secret

Run the AWS CLI command admin-initiate-auth to initiate the authentication flow as an administrator to get the ID, access token, and refresh token:

$ aws  --region us-east-1 cognito-idp admin-initiate-auth --user-pool-id us-east-1_123456789 --client-id your-client-id --auth-parameters USERNAME=user-name,PASSWORD=your-password --auth-flow ADMIN_NO_SRP_AUTH

You receive an output similar to the following:

{
    "ChallengeParameters": {},
    "AuthenticationResult": {
        "AccessToken": "eyJra....",
        "ExpiresIn": 3600,
        "TokenType": "Bearer",
        "RefreshToken": "ey.._9Dg",
        "IdToken": "ey..DU-Q"
    }
}

Run the AWS CLI command revoke-token to revoke the refresh token similar to the following:

$ aws --region us-east-1 cognito-idp revoke-token --client-id your-client-id --token eyJra....

Note: You don't receive an output.

Test using the same refresh token for getting a fresh access token and ID:

$ aws --region us-east-1 cognito-idp admin-initiate-auth --user-pool-id us-east-1_123456789 --client-id your-client-id --auth-parameters REFRESH_TOKEN=eyJra....tw --auth-flow REFRESH_TOKEN_AUTH

You receive an output that the refresh tokens revoked similar to the following:

Error: An error occurred (NotAuthorizedException) when calling the AdminInitiateAuth operation: Refresh Token has been revoked

App client with a secret

Follow the instructions to create a SecretHash value using a Python script.

Run the AWS CLI command admin-initiate-auth to initiate the authentication flow as an administrator. This gives you the ID, access token, and refresh token. This command looks similar to the following:

$ aws --region us-east-1 cognito-idp admin-initiate-auth --user-pool-id us-east-1_123456789 --client-id your-client-id --auth-parameters USERNAME=user-name,PASSWORD=your-password,SECRET_HASH=IkVyH...= --auth-flow ADMIN_NO_SRP_AUTH

You receive an output that's similar to the following:

{
    "ChallengeParameters": {},
    "AuthenticationResult": {
        "AccessToken": "eyJra....",
        "ExpiresIn": 3600,
        "TokenType": "Bearer",
        "RefreshToken": "eyJjd....",
        "IdToken": "ey..YQSA"
    }
}

Run the AWS CLI command revoke-token to revoke the refresh token:

$ aws --region us-east-1 cognito-idp revoke-token --client-id your-client-id --token eyJjd... --client-secret 1n00....

Run a test using the same refresh token to get a fresh access token and ID:

$ aws --region us-east-1 cognito-idp admin-initiate-auth --user-pool-id us-east-1_123456789 --client-id your-client-id --auth-parameters REFRESH_TOKEN=eyJjdH.... --auth-flow REFRESH_TOKEN_AUTH

You receive an output that the refresh tokens are revoked:

Error: An error occurred (NotAuthorizedException) when calling the AdminInitiateAuth operation: Refresh Token has been revoked

New added claims

Two new claims, origin_jti and jti, are added in the access and ID token, increasing in the size of the tokens in the app client.

The jti claim provides a unique identifier for the JWT. The identifier value must be assigned so that the same value can't be assigned to a different data object. If the app client uses multiple issuers, then use different values to prevent collisions.

Note: The jti claim is optional. For more information, see RFC-7519) on the Internet Engineering Task Force website.