Using the ID token
The ID token is a JSON web token
(JWT)name
, email
, and phone_number
. You can use this
identity information inside your application. The ID token can also be used to authenticate
users to your resource servers or server applications. You can also use an ID token outside of
the application with your web API operations. In those cases, you must verify the signature of
the ID token before you can trust any claims inside the ID token. See Verifying a JSON web
token.
You can set the ID token expiration to any value between 5 minutes and 1 day. You can set this value per app client.
When your user signs in with the hosted UI or a federated identity provider (IdP), Amazon Cognito sets session cookies that are valid for 1 hour. If you use the hosted UI or federation, and specify a minimum duration of less than 1 hour for your access and ID tokens, your users will still have a valid session until the cookie expires. If the user has tokens that expire during the one-hour session, the user can refresh their tokens without the need to reauthenticate.
ID Token Header
The header contains two pieces of information: the key ID (kid
), and the
algorithm (alg
).
{ "kid" : "1234example=" "alg" : "RS256", }
- Key ID (
kid
) -
The
kid
parameter is a hint that indicates which key was used to secure the JSON Web Signature (JWS) of the token.For more information about the
kid
parameter, see the Key identifier (kid) header parameter. - Algorithm (
alg
) -
The
alg
parameter represents the cryptographic algorithm that is used to secure the ID token. User pools use an RS256 cryptographic algorithm, which is an RSA signature with SHA-256.For more information about the
alg
parameter, see Algorithm (alg) header parameter.
ID Token Payload
This is a sample payload from an ID token. It contains claims about the authenticated
user. For more information about OpenID Connect (OIDC) standard claims, see the OIDC standard
claims
{ "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "aud": "xxxxxxxxxxxxexample", "email_verified": true, "token_use": "id", "auth_time": 1500009400, "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example", "cognito:username": "janedoe", "exp": 1500013000, "given_name": "Jane", "iat": 1500009400, "email": "janedoe@example.com", "jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }
- Subject (
sub
) -
The
sub
claim is a unique identifier (UUID) for the authenticated user. It is not the same as the user name, which might not be unique. - Issuer (
iss
) -
The
iss
claim has the following format:https://cognito-idp.{region}.amazonaws.com/{userPoolId}
For example, suppose you created a user pool in the
us-east-1
Region and its user pool ID isu123456
. In that case, the ID token that is issued for users of your user pool have the followingiss
claim value:https://cognito-idp.us-east-1.amazonaws.com/u123456
- Audience (
aud
) -
The content of the
aud
claim is theclient_id
that the user requested when they authenticated with your user pool. - Token use (
token_use
) -
The token_use
claim describes the intended purpose of this token. Its value is alwaysid
in the case of the ID token. - Authentication time (
auth_time
) -
The
auth_time
claim contains the 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 format. On refreshes,auth_time
represents the time when the original authentication occurred, not the time when the token was issued. - Nonce (
nonce
) -
The
nonce
claim comes from a parameter of the same name that you can add to requests to your OAuth 2.0authorize
endpoint. When you add the parameter, thenonce
claim is included in the ID token that Amazon Cognito issues, and you can use it to guard against replay attacks. If you do not provide anonce
value in your request, Amazon Cognito automatically generates and validates a nonce when you authenticate through a third-party identity provider, then adds it as anonce
claim to the ID token. The implementation of thenonce
claim in Amazon Cognito is based on OIDC standards. - Origin jti (
origin_jti
) -
The originating JWT identifier, from the time when the original authentication occurred.
- jti (
jti
) -
The
jti
claim is a unique identifier of the JWT.
The ID token can contain OIDC standard claims that are defined in OIDC standard
claims
User pool custom attributes are always prefixed with a custom: prefix.
ID Token Signature
The signature of the ID token is calculated based on the header and payload of the JWT token. When used outside of an application in your web APIs, you must always verify this signature before accepting the token. See Verifying a JSON Web Token. Verifying a JSON web token.