Pre token generation Lambda trigger
Because Amazon Cognito invokes this trigger before token generation, you can customize identity token claims.
You can use this Lambda trigger to customize an identity token before Amazon Cognito generates it. You can use this trigger to add new claims, update claims, or suppress claims in the identity token. To use this feature, associate a Lambda function from the Amazon Cognito user pools console or update your user pool through the AWS Command Line Interface (AWS CLI).
You can't modify the following claims:
acr
amr
aud
at_hash
auth_time
azp
cognito:username
exp
iat
identities
iss
jti
-
nbf
nonce
origin_jti
sub
token_use
Developer attribute claims with a
dev:
prefix
Topics
Pre token generation Lambda trigger sources
triggerSource value | Event |
---|---|
TokenGeneration_HostedAuth |
Called during authentication from the Amazon Cognito hosted UI sign-in page. |
TokenGeneration_Authentication |
Called after user authentication flows have completed. |
TokenGeneration_NewPasswordChallenge |
Called after the user is created by an admin. This flow is invoked when the user has to change a temporary password. |
TokenGeneration_AuthenticateDevice |
Called at the end of the authentication of a user device. |
TokenGeneration_RefreshTokens |
Called when a user tries to refresh the identity and access tokens. |
Pre token generation Lambda trigger parameters
The request that Amazon Cognito passes to this Lambda function is a combination of the parameters below and the common parameters that Amazon Cognito adds to all requests.
Pre token generation request parameters
- groupConfiguration
-
The input object that contains the current group configuration. The object includes
groupsToOverride
,iamRolesToOverride
, andpreferredRole
. - groupsToOverride
-
A list of the group names that correspond with the user who receives the identity token.
- iamRolesToOverride
-
A list of the current AWS Identity and Access Management (IAM) roles that correspond with these groups.
- preferredRole
-
A string that indicates the preferred IAM role.
- clientMetadata
-
One or more key-value pairs that you can specify and provide as custom input to the Lambda function for the pre token generation trigger. To pass this data to your Lambda function, use the ClientMetadata parameter in the AdminRespondToAuthChallenge and RespondToAuthChallenge API operations. Amazon Cognito doesn't include data from the ClientMetadata parameter in AdminInitiateAuth and InitiateAuth API operations in the request that it passes to the pre token generation function.
Pre token generation response parameters
- claimsToAddOrOverride
-
A map of one or more key-value pairs of claims to add or override. For group-related claims, use groupOverrideDetails instead.
- claimsToSuppress
-
A list that contains claims that you want Amazon Cognito to suppress from the identity token.
Note
If your function both suppresses and replaces a claim value, then Amazon Cognito suppresses the claim.
- groupOverrideDetails
-
The output object that contains the current group configuration. The object includes
groupsToOverride
,iamRolesToOverride
, andpreferredRole
.Your function replaces the groupOverrideDetails object with the object that you provide. If you provide an empty or null object in the response, then Amazon Cognito suppresses the groups. To keep the existing group configuration the same, copy the value of the groupConfiguration object of the request to the groupOverrideDetails object in the response. Then pass it back to the service.
Amazon Cognito ID and access tokens both contain the
cognito:groups
claim. Your groupOverrideDetails object replaces thecognito:groups
claim in access tokens and ID tokens.
Pre token generation example: Add a new claim and suppress an existing claim
This example uses the Pre Token Generation Lambda function to add a new claim and suppresses an existing claim.
Amazon Cognito passes event information to your Lambda function. The function then returns the same event object to Amazon Cognito, with any changes in the response. In the Lambda console, you can set up a test event with data that is relevant to your Lambda trigger. The following is a test event for this code sample: Because the code example doesn't process any request parameters, you can use a test event with an empty request. For more information about common request parameters, see User pool Lambda trigger event.
Pre token generation example: Modify the user's group membership
This example uses the Pre Token Generation Lambda function to modify the user's group membership.
Amazon Cognito passes event information to your Lambda function. The function then returns the same event object to Amazon Cognito, with any changes in the response. In the Lambda console, you can set up a test event with data that is relevant to your Lambda trigger. The following is a test event for this code sample: