Menu
Sign In to the Console
Amazon Cognito
Developer Guide

AWS Documentation » Amazon Cognito » Developer Guide » Amazon Cognito User Pools » Authentication with a User Pool » Using Tokens with User Pools

Using Tokens with User Pools

After a successful authentication, your web or mobile app will receive bearer tokens from Amazon Cognito.

Authentication overview

These are the tokens defined by the OpenID Connect specification:

  • ID token

  • Access token

  • Refresh token

Important

We strongly recommended that you secure all tokens in transit and storage in the context of your application.

Using the ID Token

The ID token is represented as a JSON Web Token (JWT). The token contains claims about the identity of the authenticated user. For example, it includes claims such as name, family_name, phone_number, etc. For more information about standard claims, see the OpenID Connect specification. A client app can use this identity information inside the application. The ID token can also be used to authenticate users against your resource servers or server applications. When an ID token is used outside of the application against your web APIs, you must verify the signature of the ID token before you can trust any claims inside the ID token.

The ID token expires one hour after the user authenticates. You should not process the ID token in your client or web API after it has expired.

Using the Access Token

The access token is also represented as a JSON Web Token (JWT). It contains claims about the authenticated user, but unlike the ID token, it does not include all of the user's identity information. The primary purpose of the access token is to authorize operations in the context of the user in the user pool. For example, you can use the access token against a user pool to update or delete user attributes. The access token can also be used with any of your web APIs to make access control decisions and authorize operations in the context of the user. As with the ID token, you must first verify the signature of the access token in your web APIs before you can trust any claims inside the access token.

The access token expires one hour after the user authenticates. It should not be processed after it has expired.

Using the Refresh Token

To use the refresh token to get new tokens, use the InitiateAuth, or the AdminInitiateAuth API methods. The auth flow type is REFRESH_TOKEN_AUTH. The authorization parameters, AuthParameters, are a key-value map where the key is "REFRESH_TOKEN" and value is the actual refresh token.

This initiates the token refresh process with the Amazon Cognito server and returns new ID and access tokens.

By default, the refresh token expires 30 days after the user authenticates. When you create an app for your user pool, you can set the app's Refresh token expiration (days) to any value between 1 and 3650.

Note

The user account itself never expires, as long as the user has logged in at least once before the UnusedAccountValidityDays time limit for new accounts.

Your tokens will be refreshed automatically by the Mobile SDK for iOS and the Mobile SDK for Android where the tokens are guaranteed to be valid for at least 5 minutes by default.

Note

The Mobile SDK for Android offers the option to change the minimum validity period of the token to a value between 0 and 30 minutes. See the setRefreshThreshold() method of CognitoIdentityProviderClientConfig in the AWS Mobile SDK for Android API Reference

Structure of ID Tokens

ID tokens are JSON Web Tokens (JWT) and can be broken down into three parts:

  1. Header

  2. Payload

  3. Signature

The JWT consists of a header, payload, and signature encoded as Base64url strings separated by dot "." characters.

11111111111.22222222222.33333333333
1. Header

The header contains two pieces of information: the kid and the alg. A kid value is used to locate the public key. For example, to verify a signature, retrieve the kid from the JWT token to find the corresponding public key.

The public key should verify the ID token signature. The alg value represents the cryptographic algorithm used to secure IdToken. Currently, user pools use RS256 as the cryptographic algorithm.

For more information, see JSON Web Token (JWT).

For example, the header will look like this:

{
"alg" : "RS256",
"kid" : "samplekid****"
}
2. Payload

The payload contains claims as per the JWT specification. For more information, see RFC7519. The following are details of some specific claims:

  • iss : The issuer. It has the following format: https://cognito-idp.{region}.amazonaws.com/{userPoolId}. For example, if you created a user pool in the us-east-1 region and its ID is u123456, the ID token issued for users of your user pool have an iss claim value of https://cognito-idp.us-east-1.amazonaws.com/u123456.

  • sub : The UUID of the authenticated user. This is not the same as username.

  • aud : Contains the client_id with which the user authenticated.

  • token_use : The intended purpose of this token. Its value is always id in the case of the ID token.

  • auth_time : Time when the authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. On refreshes, it represents the time when the original authentication occurred, not the time when the token was issued.

Additionally, the ID token contains standard claims defined in the OIDC Core spec, Section 5.1. It also contains the custom attributes that you define in your user pool. The custom attributes are always prefixed with the custom: prefix.

3. Signature

The signature of the ID token is calculated based on the header and payload of the ID token. When used outside of an application in your web APIs, you must always verify this signature before processing the ID token.

Structure of Access Tokens

Access tokens are also JSON Web Tokens (JWT) and can be broken down into three parts:

  1. Header

  2. Payload

  3. Signature

The JWT consists of a header, payload, and signature encoded as Base64url strings separated by dot "." characters.

11111111111.22222222222.33333333333
1. Header

The header for the access token will be the same structure as the ID token, but the kid will be different because different keys are used to sign ID tokens and access tokens.

2. Payload

The payload contains claims as per the JWT specification. For more information, see RFC7519. The following are details of some specific claims:

  • iss : The issuer. It has the following format: https://cognito-idp.{region}.amazonaws.com/{userPoolId}. For example, if you created a user pool in the us-east-1 region and its ID is u123456, the ID token issued for users of your user pool have an iss claim value of https://cognito-idp.us-east-1.amazonaws.com/u123456.

  • client_id : The client app that was issued this access token.

  • username : The user name of the authenticated user.

  • sub : The UUID of the authenticated user. This is not the same as username.

  • token_use : The intended purpose of this token. Its value is always access in the case of the access token.

  • auth_time : Time when the authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. On refreshes, it represents the time when the original authentication occurred, not the time when the token was issued.

3. Signature

The signature of the access token is calculated based on the header and payload of the access token. You should always verify this signature if you use access tokens in your web APIs.

Using ID Tokens and Access Tokens in your Web APIs

Since both the ID token and the access token are JSON Web Tokens (JWT), you may use any of the available JWT libraries to decode the JWT and verify the signature. For example, if your platform is Java, you could use the Nimbus JOSE and JWT library. The following procedure describes the high level steps you must implement to process the ID token and the access token on the server side.

To verify a signature for ID and access tokens

  1. Download and store the JSON Web Key (JWK) for your user pool. You can locate it at https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json.

    Each JWK should be stored against its kid.

    Note

    This is a one time step before your web APIs can process the tokens. Now you can perform the following steps each time the ID token or the access token are used against your web APIs.

  2. Decode the token string into JWT format.

  3. Check the iss claim. It should match your user pool. For example, a user pool created in the us-east-1 region will have an iss value of https://cognito-idp.us-east-1.amazonaws.com/{userPoolId}.

  4. Check the token_use claim.

    If you are only accepting the access token in your web APIs, its value must be access.

    If you are only using the ID token, its value must be id.

    If you are using both tokens, the value is either id or access.

  5. Get the kid from the JWT token header and retrieve the corresponding JSON Web Key that was stored in step 1.

  6. Verify the signature of the decoded JWT token.

  7. Check the exp claim and make sure the token is not expired.

    You can now trust the claims inside the token and use it as it fits your requirements.

Revoking All Tokens for a User

Users can sign out from all devices where they are currently signed in when you revoke all of the user's tokens by using the GlobalSignOut and AdminUserGlobalSignOut APIs. After the user has been signed out:

  • The user's refresh token cannot be used to get new tokens for the user.

  • The user's access token cannot be used against the user pools service.

  • The user must reauthenticate to get new tokens.

An app can use the GlobalSignOut API to allow individual users to sign themselves out from all devices. Typically an app would present this option as a choice, such as Sign out from all devices. The app must call this method with the user's valid, nonexpired, nonrevoked access token. This method cannot be used to allow a user to sign out another user.

An administrator app can use the AdminUserGlobalSignOut API to allow administrators to sign out a user from all devices. The administrator app must call this method with AWS developer credentials and pass the user pool ID and the user's username as parameters. The AdminUserGlobalSignOut API can sign out any user in the user pool.