AWS cognito: Cognito ID token claims: safe parsing guidance and claim types
Summary
Clarifies that the ID token payload example is non-exhaustive, adds guidance to parse each claim as the documented type without imposing stricter formats, specifies concrete types for claims (groups, cognito:roles, client_id, identities, auth_time, exp, iat, iss), documents serialization quirks of the identities claim (string "true"/"false" for primary, string Unix-ms dateCreated, nullable issuer), and adds the email claim.
Security assessment
The added text directs developers to parse Cognito tokens safely and to read claims (including authorization-relevant ones like cognito:groups and cognito:roles) as their documented types rather than imposing stricter validation, which reduces the risk of mis-parsing claims that drive access decisions. It is best-practice/hardening guidance rather than a fix for a specific vulnerability or incident, so it is not marked security_issue_related.
Evidence
+This payload is representative, not exhaustive. The set of claims in a Amazon Cognito ID token grows over time as new features add new claims, so the claims that your tokens carry can differ from this example. Treat this example as a snapshot of common claims rather than a complete, fixed list, and read How to parse this token safely before you write code that parses Amazon Cognito tokens.
Diff
diff --git a/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.md b/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.md index 1d47c08..aa22b3e 100644 --- a//cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.md +++ b//cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.md @@ -48,0 +49,2 @@ This is a example payload from an ID token. It contains claims about the authent +This payload is representative, not exhaustive. The set of claims in a Amazon Cognito ID token grows over time as new features add new claims, so the claims that your tokens carry can differ from this example. Treat this example as a snapshot of common claims rather than a complete, fixed list, and read How to parse this token safely before you write code that parses Amazon Cognito tokens. + @@ -95 +97 @@ A unique identifier ([UUID](./cognito-terms.html#terms-uuid)), or subject, for t -Amazon Cognito generates `sub` in an Amazon Cognito-specific format that doesn't conform to a specific UUID format, including RFC UUID. You shouldn't strictly validate the format of `sub`. +Amazon Cognito generates `sub` in an Amazon Cognito-specific format that doesn't conform to a specific UUID format, including RFC UUID. You shouldn't strictly validate the format of `sub`. More generally, as described in How to parse this token safely, read each claim as the type that this page documents and don't impose a stricter format than the documentation states. @@ -100 +102 @@ Amazon Cognito generates `sub` in an Amazon Cognito-specific format that doesn't -An array of the names of user pool groups that have your user as a member. Groups can be an identifier that you present to your app, or they can generate a request for a preferred IAM role from an identity pool. +An array of strings. Each string is the name of a user pool group that has your user as a member. Groups can be an identifier that you present to your app, or they can generate a request for a preferred IAM role from an identity pool. This claim is always an array, even when the user belongs to a single group. @@ -110 +112 @@ The ARN of the IAM role that you associated with your user's highest-priority us -The issuer of the token. This claim identifies the user pool that generated the token. Your application should validate that this value matches your user pool's expected issuer URL. The claim has the following format. +A single string. The issuer of the token. This claim identifies the user pool that generated the token. Your application should validate that this value matches your user pool's expected issuer URL. The claim has the following format. @@ -134 +136 @@ A token-revocation identifier associated with your user's refresh token. Amazon -An array of the names of the IAM roles associated with your user's groups. Every user pool group can have one IAM role associated with it. This array represents all IAM roles for your user's groups, regardless of precedence. For more information, see [Adding groups to a user pool](./cognito-user-pools-user-groups.html). +An array of strings. Each string is the ARN of an IAM role associated with one of your user's groups. Every user pool group can have one IAM role associated with it. This array represents all IAM roles for your user's groups, regardless of precedence, and is always an array even when it contains a single role. For more information, see [Adding groups to a user pool](./cognito-user-pools-user-groups.html). @@ -139 +141 @@ An array of the names of the IAM roles associated with your user's groups. Every -The user pool app client that authenticated your user. Amazon Cognito renders the same value in the access token `client_id` claim. +A single string. The user pool app client that authenticated your user. Amazon Cognito renders the same value in the access token `client_id` claim. @@ -144 +146 @@ The user pool app client that authenticated your user. Amazon Cognito renders th -The contents of the user's `identities` attribute. The attribute contains information about each third-party identity provider profile that you've linked to a user, either by federated sign-in or by [linking a federated user to a local profile](./cognito-user-pools-identity-federation-consolidate-users.html). This information contains their provider name, their provider unique ID, and other metadata. +An array of objects. Each object describes one third-party identity provider profile that you've linked to the user, either by federated sign-in or by [linking a federated user to a local profile](./cognito-user-pools-identity-federation-consolidate-users.html). Each object contains the fields `userId` (the user's unique ID at the provider), `providerName`, `providerType`, `issuer`, `primary`, and `dateCreated`. All of these fields are strings, with two serialization details to parse carefully: `primary` is the string `"true"` or `"false"`, not a JSON boolean, and `dateCreated` is a string that holds Unix time in milliseconds (for example `"1642699117273"`), not a number. The `issuer` field can be `null`. This claim is always an array, even when the user has one linked identity. @@ -154 +156 @@ The intended purpose of the token. In an ID token, its value is `id`. -The authentication time, in Unix time format, that your user completed authentication. +A number. The authentication time, in Unix time format, when your user completed authentication. @@ -159 +161 @@ The authentication time, in Unix time format, that your user completed authentic -The expiration time, in Unix time format, that your user's token expires. +A number. The expiration time, in Unix time format, when your user's token expires. @@ -164 +166 @@ The expiration time, in Unix time format, that your user's token expires. -The issued-at time, in Unix time format, that Amazon Cognito issued your user's token. +A number. The issued-at time, in Unix time format, when Amazon Cognito issued your user's token. @@ -170,0 +173,5 @@ The unique identifier of the JWT. +**`email`** + + +A single string. The email address of your user, when the `email` attribute is present and readable by the app client. +