AWS cognito documentation change
Summary
Updated documentation for Amazon Cognito's pre-token generation Lambda trigger, including changes to event versions, excluded claims and scopes, and token customization capabilities. Removed references to version 3 (V3_0) events and machine-to-machine (M2M) authorization. Added detailed list of excluded claims and scopes that cannot be modified in tokens.
Security assessment
The changes primarily focus on updating documentation about token customization capabilities and event versions. While it includes information about excluded claims and scopes, there is no evidence of addressing a specific security vulnerability or incident.
Diff
diff --git a/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.md index 23c939257..55439afca 100644 --- a/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.md +++ b/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.md @@ -5 +5 @@ -Event versionsClaims and scopes referenceCustomizing the identity tokenCustomizing the access tokenPre token generation Lambda trigger sourcesPre token generation Lambda trigger parametersPre token trigger event version two example: Add and suppress claims, scopes, and groupsPre token generation event version two example: Add claims with complex objectsPre token generation event version one example: Add a new claim and suppress an existing claim Pre token generation event version one example: Modify the user's group membership +Event versionsExcluded claims and scopesCustomizing the identity tokenCustomizing the access tokenPre token generation Lambda trigger sourcesPre token generation Lambda trigger parametersPre token trigger event version two example: Add and suppress claims, scopes, and groupsPre token generation event version two example: Add claims with complex objectsPre token generation event version one example: Add a new claim and suppress an existing claim Pre token generation event version one example: Modify the user's group membership @@ -9 +9 @@ Event versionsClaims and scopes referenceCustomizing the identity tokenCustomizi -Because Amazon Cognito invokes this trigger before token generation, you can customize the claims in user pool tokens. With the **Basic features** of the version one or `V1_0` pre token generation trigger event, you can customize the identity (ID) token. In user pools with the Essentials or Plus feature plan, you can generate the version two or `V2_0` trigger event with access token customization, and the version three or `V3_0` trigger event with access token customization for machine-to-machine (M2M) client-credentials grants. +Because Amazon Cognito invokes this trigger before token generation, you can customize the claims in user pool tokens. With the **Basic features** of the version one or `V1_0` pre token generation trigger event, you can customize the identity (ID) token. In user pools with the Essentials or Plus feature plan, you can generate the version 2 or `V2_0` trigger event with **access token customization**. @@ -11,3 +11 @@ Because Amazon Cognito invokes this trigger before token generation, you can cus -Amazon Cognito sends a `V1_0` event as a request to your function with data that it would write to the ID token. A `V2_0` or `V3_0` event is a single request with the data that Amazon Cognito would write to both the identity and access tokens. To customize both tokens, you must update your function to use trigger version two or three, and send data for both tokens in the same response. - -Amazon Cognito applies version two event responses to access tokens from user authentication, where a human user has presented credentials to your user pool. Version three event responses apply to access tokens from user authentication and machine authentication, where automated systems authorize access token requests with app client secrets. Aside from the circumstances of the resulting access tokens, version two and three events are identical. +Amazon Cognito sends a `V1_0` event as a request to your function with data that it would write to the ID token. A `V2_0` event is a single request with the data that Amazon Cognito would write to both the identity and access tokens. To customize both tokens, you must update your function to use the most recent trigger version, and send data for both tokens in the same response. @@ -19 +17 @@ This Lambda trigger can add, remove, and modify some claims in identity and acce -Your user pool can deliver different versions of a pre token generation trigger event to your Lambda function. A `V1_0` trigger delivers the parameters for modification of ID tokens. A `V2_0` or `V3_0` trigger delivers parameters for the following. +Your user pool can deliver different versions of a pre token generation trigger event to your Lambda function. A `V1_0` trigger delivers the parameters for modification of ID tokens. A `V2_0` trigger delivers parameters for the following. @@ -44 +42,57 @@ In the ID token, you can populate complex objects to the values of claims except -User pools deliver `V1_0` events by default. To configure your user pool to send a `V2_0` event, choose a **Trigger event version** of **Basic features + access token customization for user identities** when you configure your trigger in the Amazon Cognito console. To produce `V3_0` events, choose ****Basic features + access token customization for user and machine identities****. You can also set the value of `LambdaVersion` in the [LambdaConfig](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html#CognitoUserPools-UpdateUserPool-request-LambdaConfig) parameters in an [UpdateUserPool ](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) or [CreateUserPool ](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) API request. Event versions one, two, and three are available in the **Essentials** and **Plus** feature plans. M2M operations for version three events have a pricing structure separate from the monthly active users (MAU) formula. For more information, see [Amazon Cognito Pricing](https://aws.amazon.com/cognito/pricing/). +User pools deliver `V1_0` events by default. To configure your user pool to send a `V2_0` event, choose a **Trigger event version** of **Basic features + access token customization** when you configure your trigger in the Amazon Cognito console. You can also set the value of `LambdaVersion` in the [LambdaConfig](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html#CognitoUserPools-UpdateUserPool-request-LambdaConfig) parameters in an [UpdateUserPool ](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) or [CreateUserPool ](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) API request. Additional costs apply to access token customization with `V2_0` events. For more information, see [Amazon Cognito Pricing](https://aws.amazon.com/cognito/pricing/). + +## Excluded claims and scopes + +Amazon Cognito limits the claims and scopes that you can add, modify, or suppress in access and identity tokens. If your Lambda function attempts to set a value for any of these claims, Amazon Cognito issues a token with the original claim value, if one was present in the request. + +###### Shared claims + + * `acr` + + * `amr` + + * `at_hash` + + * `auth_time` + + * `azp` + + * `exp` + + * `iat` + + * `iss` + + * `jti` + + * `nbf` + + * `nonce` + + * `origin_jti` + + * `sub` + + * `token_use` + + + + +###### ID token claims + + * `identities` + + * `aud` + + * `cognito:username` + + + + +###### Access token claims + + * `username` + + * `client_id` + + * `scope` @@ -48,47 +102,23 @@ User pools deliver `V1_0` events by default. To configure your user pool to send -User pools that were operational with the **Advanced security features** option on or before November 22, 2024 at 1800 GMT, and that remain on the **Lite** feature tier have access to event versions one and two of the pre token generation trigger. User pools in this legacy tier _without_ advanced security features have access to event version one. Version three is _only_ available in Essentials and Plus. - -## Claims and scopes reference - -Amazon Cognito limits the claims and scopes that you can add, modify, or suppress in access and identity tokens. The following table describes the claims that your Lambda function can and can't modify, and the trigger event parameters that affect the presence or value of the claim. - -Claim | Default token type | Can add? | Can modify? | Can suppress? | Event parameter - add or modify | Event parameter - suppress | Identity type | Event version ----|---|---|---|---|---|---|---|--- -Any claim not in the user pool token schema | None | Yes | Yes | N/A | `claimsToAddOrOverride` | `claimsToSuppress` | User, machine1 | All2 -`scope` | Access | Yes | Yes | Yes | `scopesToAdd` | `scopesToSuppress` | User, machine1 | `v2_0`, `v3_0` -`cognito:groups` | ID, Access | Yes | Yes | Yes | `groupsToOverride` | `claimsToSuppress` | User | All2 -`cognito:preferred_role` | ID | Yes | Yes | Yes | `preferredRole` | `claimsToSuppress`3 | User | All -`cognito:roles` | ID | Yes | Yes | Yes | `iamRolesToOverride` | `claimsToSuppress`3 | User | All -`cognito:username` | ID | No | No | No | N/A | N/A | User | N/A -Any other claim with a `cognito:` prefix | None | No | No | No | N/A | N/A | N/A | N/A -`username` | Access | No | No | No | N/A | N/A | User | `v2_0`, `v3_0` -`sub` | ID, Access | No | No | No | N/A | N/A | User | N/A -standard OIDC attribute | ID | Yes | Yes | Yes | `claimsToAddOrOverride` | `claimsToSuppress` | User | All -`custom:` attribute | ID | Yes | Yes | Yes | `claimsToAddOrOverride` | `claimsToSuppress` | User | All -`dev:` attribute | ID | No | No | Yes | N/A | `claimsToSuppress` | User | All -`identities` | ID | No | No | No | N/A | N/A | User | N/A -`aud`4 | ID | No | No | No | N/A | N/A | User, machine | N/A -`client_id` | Access | No | No | No | N/A | N/A | User, machine | N/A -`event_id` | Access | No | No | No | N/A | N/A | User, machine | N/A -`device_key` | Access | No | No | No | N/A | N/A | User | N/A -`version` | Access | No | No | No | N/A | N/A | User, machine | N/A -`acr` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`amr` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`at_hash` | ID | No | No | No | N/A | N/A | User, machine | N/A -`auth_time` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`azp` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`exp` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`iat` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`iss` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`jti` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`nbf` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`nonce` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`origin_jti` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A -`token_use` | ID, Access | No | No | No | N/A | N/A | User, machine | N/A - -1 Access tokens for machine identities are only available with `v3_0` of the trigger input event. Event version three is only available in the **Essentials** and **Plus** feature tiers. User pools on the **Lite** tier can receive `v1_0` events. User pools on the **Lite** tier with advanced security features can receive `v1_0` and `v2_0` events. - -2 Configure your pre token generation trigger to event version `v1_0` for ID token only, `v2_0` for ID and access token, `v3_0` for ID and access token with capabilities for machine identities. - -3 To suppress the `cognito:preferred_role` and `cognito:roles` claims, add `cognito:groups` to `claimsToSuppress`. - -4 You can add an `aud` claim to access tokens, but its value must match the app client ID of the current session. You can derive the client ID in the request event from `event.callerContext.clientId`. +You can change the scopes in an access token with `scopesToAdd` and `scopesToSuppress` response values, but you can't modify the `scope` claim directly. You can't add scopes that begin with `aws.cognito`, including the user pools reserved scope `aws.cognito.signin.user.admin`. + + * `device_key` + + * `event_id` + + * `version` + + + + +You can’t add or override claims with the following prefixes but you can suppress them, or prevent them from appearing in the token. + + * `dev:` + + * `cognito:` + + + + +The IAM role claims `cognito:roles` and `cognito:preferred_role` are linked to user pool groups by default. To suppress these claims, suppress `cognito:groups` in the `claimsToSuppress` object. + +You can add an `aud` claim to access tokens, but its value must match the app client ID of the current session. You can derive the client ID in the request event from `event.callerContext.clientId`. @@ -98 +128 @@ standard OIDC attribute | ID | Yes | Yes | Yes | `claimsToAddOrOverride` | `clai -With all event versions of the pre token generation Lambda trigger, you can customize the content of an identity (ID) token from your user pool. The ID token provides user attributes from a trusted identity source for sign-in to a web or mobile app. For more information about ID tokens, see [Understanding the identity (ID) token](./amazon-cognito-user-pools-using-the-id-token.html). +With the pre token generation Lambda trigger, you can customize the content of an identity (ID) token from your user pool. The ID token provides user attributes from a trusted identity source for sign-in to a web or mobile app. For more information about ID tokens, see [Understanding the identity (ID) token](./amazon-cognito-user-pools-using-the-id-token.html). @@ -115 +145 @@ The uses of the pre token generation Lambda trigger with an ID token include the -With event versions two and three of the pre token generation Lambda trigger, you can customize the content of an access token from your user pool. The access token authorizes users to retrieve information from access-protected resources like Amazon Cognito token-authorized API operations and third-party APIs. For machine-to-machine (M2M) authorization with a client credentials grant, Amazon Cognito only invokes the pre token generation trigger when your user pool is configured for a version three (`V3_0`) event. For more information about access tokens, see [Understanding the access token](./amazon-cognito-user-pools-using-the-access-token.html). +With the pre token generation Lambda trigger, you can customize the content of an access token from your user pool. The access token authorizes users to retrieve information from access-protected resources like Amazon Cognito token-authorized API operations and third-party APIs. Although you can generate access tokens for machine-to-machine (M2M) authorization with Amazon Cognito with a client credentials grant, M2M requests don’t invoke the pre token generation trigger function and can't issue customized access tokens. For more information about access tokens, see [Understanding the access token](./amazon-cognito-user-pools-using-the-access-token.html). @@ -119 +149 @@ The uses of the pre token generation Lambda trigger with an access token include - * Add or suppress scopes in the `scope` claim. For example, you can add scopes to an access token that resulted from Amazon Cognito user pools API authentication, which only assigns the scope `aws.cognito.signin.user.admin`. + * Add or suppress OAuth 2.0 scopes in the `scope` claim. For example, you can add scopes to an access token that resulted from Amazon Cognito user pools API authentication, which only assigns the scope `aws.cognito.signin.user.admin`. @@ -147 +177 @@ AWS Management Console - 6. Choose a **Trigger event version** of **Basic features + access token customization for user identities** or **Basic features + access token customization for user and machine identities**. This setting updates the request parameters that Amazon Cognito sends to your function to include fields for access token customization. + 6. Choose a **Trigger event version** of **Basic features + access token customization**. This setting updates the request parameters that Amazon Cognito sends to your function to include fields for access token customization. @@ -159 +189 @@ Generate a [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-po -Include the following content in the `LambdaVersion` parameter of your request. A `LambdaVersion` value of `V2_0` causes your user pool to add parameters for, and apply changes to, access tokens. A `LambdaVersion` value of `V3_0` produces the same event as `V2_0`, but causes your user pool to _also_ apply changes to M2M access tokens. To invoke a specific function version, use a Lambda function ARN with a function version as the value of `LambdaArn`. +Include the following content in the `LambdaVersion` parameter of your request. A `LambdaVersion` value of `V2_0` causes your user pool to add parameters for access token customization. To invoke a specific function version, use a Lambda function ARN with a function version as the value of `LambdaArn`. @@ -164 +194 @@ Include the following content in the `LambdaVersion` parameter of your request. - **"LambdaVersion": "V3_0"** + **"LambdaVersion": "V2_0"** @@ -192 +221,0 @@ triggerSource value | Event -`TokenGeneration_ClientCredentials` | Called after an M2M client credentials grant. Your user pool only sends this event when your event version is `V3_0`. @@ -200 +229 @@ The request that Amazon Cognito passes to this Lambda function is a combination -Version one +Version 1 @@ -203 +232 @@ Version one -The version one token can set group membership, IAM roles, and new claims in ID tokens. Group membership overrides also apply to the `cognito:groups` claim in access tokens. +The version 1 token can set group membership, IAM roles, and new claims in ID tokens. Group membership overrides also apply to the `cognito:groups` claim in access tokens. @@ -244 +273 @@ The version one token can set group membership, IAM roles, and new claims in ID -Versions two and three +Version 2 @@ -247 +276 @@ Versions two and three -The versions two and three request events add fields that customize the access token. User pools apply changes from version three events to access tokens for machine identities. These versions also add support for complex `claimsToOverride` data types in the response object. Your Lambda function can return the following types of data in the value of `claimsToOverride`: +The version 2 request event adds fields that customize the access token. It also adds support for complex `claimsToOverride` data types in the response object. Your Lambda function can return the following types of data in the value of `claimsToOverride`: @@ -313 +342 @@ clientMetadata | One or more key-value pairs that you can specify and provide a -scopes | Access token scopes. The scopes that are present in an access token are the user pool standard and custom scopes that your user requested, and that you authorized your app client to issue. | 2 +scopes | Your user's OAuth 2.0 scopes. The scopes that are present in an access token are the user pool standard and custom scopes that your user requested, and that you authorized your app client to issue. | 2 @@ -320,5 +349,5 @@ claimsOverrideDetails | A container for all elements in a `V1_0` trigger event. -claimsAndScopeOverrideDetails | A container for all elements in a `V2_0` or `V3_0` trigger event. | 2 -idTokenGeneration | The claims that you want to override, add, or suppress in your user’s ID token. This parent to ID token customization values appears only in event version 2 and above, but the child elements appear in version 1 events. | 2 -accessTokenGeneration | The claims and scopes that you want to override, add, or suppress in your user’s access token. This parent to access token customization values appears only in event version 2 and above. | 2 -claimsToAddOrOverride | A map of one or more claims and their values that you want to add or modify. For group-related claims, use `groupOverrideDetails` instead. In event version 2 and above, this element appears under both `accessTokenGeneration` and `idTokenGeneration`. | 1* -claimsToSuppress | A list of claims that you want Amazon Cognito to suppress. If your function both suppresses and replaces a claim value, then Amazon Cognito suppresses the claim. In event version 2 and above, this element appears under both `accessTokenGeneration` and `idTokenGeneration`. | 1 +claimsAndScopeOverrideDetails | A container for all elements in a `V2_0` trigger event. | 2 +idTokenGeneration | The claims that you want to override, add, or suppress in your user’s ID token. This parent to ID token customization values appears only in version 2 events, but the children elements appear in version 1 events. | 2 +accessTokenGeneration | The claims and scopes that you want to override, add, or suppress in your user’s access token. This parent to access token customization values appears only in version 2 events. | 2 +claimsToAddOrOverride | A map of one or more claims and their values that you want to add or modify. For group-related claims, use `groupOverrideDetails` instead. In version 2 events, this element appears under both `accessTokenGeneration` and `idTokenGeneration`. | 1* +claimsToSuppress | A list of claims that you want Amazon Cognito to suppress. If your function both suppresses and replaces a claim value, then Amazon Cognito suppresses the claim. In version 2 events, this element appears under both `accessTokenGeneration` and `idTokenGeneration`. | 1 @@ -326,2 +355,2 @@ groupOverrideDetails | The output object that contains the current group config -scopesToAdd | A list of scopes that you want to add to the `scope` claim in your user's access token. You can't add scope values that contain one or more blank-space characters. | 2 -scopesToSuppress | A list of scopes that you want to remove from the `scope` claim in your user's access token. | 2 +scopesToAdd | A list of OAuth 2.0 scopes that you want to add to the `scope` claim in your user's access token. You can't add scope values that contain one or more blank-space characters. | 2 +scopesToSuppress | A list of OAuth 2.0 scopes that you want to remove from the `scope` claim in your user's access token. | 2 @@ -329 +358 @@ scopesToSuppress | A list of scopes that you want to remove from the `scope` cl