AWS cognito medium security documentation change
Summary
Clarified access token scope permissions, token expiration behavior, revocation mechanics, scope definitions, and signature validation requirements. Added explicit guidance about API authorizer configuration for signature verification.
Security assessment
The changes emphasize proper token scope management (e.g., distinguishing between openid and aws.cognito.signin.user.admin scopes), clarify revocation mechanics (invalidating tokens via origin_jti), and explicitly require signature validation against JWKS endpoint. These updates address security best practices for token handling and API authorization, reducing risks of privilege escalation and token tampering.
Diff
diff --git a/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.md b/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.md index 8dc61ef33..6a66d018c 100644 --- a//cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.md +++ b//cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.md @@ -15 +15,3 @@ With the Essentials or Plus [feature plan](./cognito-sign-in-feature-plans.html) -Your user's access token is permission to request more information about your user's attributes from the [userInfo endpoint](./userinfo-endpoint.html). Your user's access token is also permission to read and write user attributes. The level of access to attributes that your access token grants depends on the permissions you assign to your app client, and the scopes that you grant in the token. +A user's access token with the `openid` scope is permission to request more information about your user's attributes from the [userInfo endpoint](./userinfo-endpoint.html). The amount of information from the `userInfo` endpoint derives from the additional scopes in the access token: for example, `profile` for all user data, `email` for their email address. + +A user's access token with the `aws.cognito.signin.user.admin` scope is permission to read and write user attributes, list authentication factors, configure multi-factor authentication (MFA) preferences, and manage remembered devices. The level of access to attributes that your access token grants to this scope matches the attribute read/write permissions you assign to your app client. @@ -21 +23 @@ The access token is a [JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7 -For access and ID tokens, don't specify a minimum less than an hour if you use managed login. Amazon Cognito HostedUI uses cookies that are valid for an hour. If you enter a minimum less than an hour, you won't get a lower expiry time. +For access and ID tokens, don't specify a minimum less than an hour if you use managed login. Managed login sets browsers cookies that are valid for one hour. If you configure an access token duration of less than an hour, this has no effect on the validity of the managed login cookie and users' ability to reauthenticate without additional credentials for one hour after initial sign-in. @@ -89 +91 @@ The identity provider that issued the token. The claim has the following format. -`https://cognito-idp.`<Region>`.amazonaws.com/`<your user pool ID>`` +`https://cognito-idp.`us-east-1`.amazonaws.com/`us-east-1_EXAMPLE`` @@ -99 +101 @@ The user pool app client that authenticated your user. Amazon Cognito renders th -A token-revocation identifier associated with your user's refresh token. Amazon Cognito references the `origin_jti` claim when it checks if you revoked your user's token with the [Revoke endpoint](./revocation-endpoint.html) or the [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) API operation. When you revoke a token, Amazon Cognito invalidates all access and ID tokens with the same `origin_jti` value. +A token-revocation identifier associated with your user's refresh token. Amazon Cognito references the `origin_jti` claim when it checks if you revoked your user's token with the [Revoke endpoint](./revocation-endpoint.html) or the [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) API operation. When you revoke a token, Amazon Cognito no longer validates access and ID tokens with the same `origin_jti` value. @@ -109 +111 @@ The intended purpose of the token. In an access token, its value is `access`. -A list of OAuth 2.0 scopes that define what access the token provides. A token from the [Token endpoint](./token-endpoint.html) can contain any scopes that your app client supports. A token from Amazon Cognito API sign-in only contains the scope `aws.cognito.signin.user.admin`. +A list of OAuth 2.0 scopes issued to the signed-in user. Scopes define the access that the token provides to external APIs, user self-service operations, and user data on the `userInfo` endpoint. A token from the [Token endpoint](./token-endpoint.html) can contain any scopes that your app client supports. A token from Amazon Cognito API sign-in only contains the scope `aws.cognito.signin.user.admin`. @@ -134 +136 @@ The unique identifier of the JWT. -The username of your user in your user pool. +The user's username in the user pool. @@ -145 +147 @@ The username of your user in your user pool. -The signature of the access 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. For more information, see [Verifying JSON web tokens](./amazon-cognito-user-pools-using-tokens-verifying-a-jwt.html). +The signature of the access token, signed with the key advertised at the `.well-known/jwks.json` endpoint, validates the integrity of the token header and payload. When you use access tokens to authorize access to external APIs, always configure your API authorizer to verify this signature against the key that signed it. For more information, see [Verifying JSON web tokens](./amazon-cognito-user-pools-using-tokens-verifying-a-jwt.html).