Menu
Amazon Cognito
Developer Guide

Pre Token Generation Lambda Trigger

Amazon Cognito invokes this trigger before token generation allowing you to customize identity token claims.

This Lambda trigger allows you to customize an identity token before it is generated. You can use this trigger to add new claims, update claims, or suppress claims in the identity token. To use this feature, you can associate a Lambda function from the Amazon Cognito User Pools console or by updating your user pool through the AWS CLI.

There are some claims which cannot be modified. These include acr, amr, aud, auth_time,azp, exp, iat, identities, iss, sub, token_use, and cognito:username.

Pre Token Generation Lambda Trigger Sources

triggerSource value Triggering 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

These are the parameters required by this Lambda function in addition to the common parameters.

JSON
JSON
{ "request": { "userAttributes": { "string": "string", .... } "groupConfiguration": { "groupsToOverride": ["string", ....], "iamRolesToOverride": ["string", ....], "preferredRole": "string" }, "response": { "claimsOverrideDetails": { "claimsToAddOrOverride": { "string": "string", .... }, "claimsToSuppress": ["string", ....], "groupOverrideDetails": { "groupsToOverride": ["string", ....], "iamRolesToOverride": ["string", ....], "preferredRole": "string" } } } }

Pre Token Generation Request Parameters

groupConfiguration

The input object containing the current group configuration. It includes groupsToOverride, iamRolesToOverride, and preferredRole.

groupsToOverride

A list of the group names that are associated with the user that the identity token is issued for.

iamRolesToOverride

A list of the current IAM roles associated with these groups.

preferredRole

A string indicating the preferred IAM role.

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 to be suppressed from the identity token.

Note

If a value is both suppressed and replaced, then it will be suppressed.

groupOverrideDetails

The output object containing the current group configuration. It includes groupsToOverride, iamRolesToOverride, and preferredRole.

The groupOverrideDetails object is replaced with the one you provide. If you provide an empty or null object in the response, then the groups are suppressed. To leave the existing group configuration as is, copy the value of the request's groupConfiguration object to the groupOverrideDetails object in the response, and pass it back to the service.

Pre Token Generation Example: Add a New Claim and Suppress an Existing Claim

This example uses the Pre Token Generation Lambda to add a new claim and suppresses an existing one.

Node.js
Node.js
exports.handler = (event, context, callback) => { event.response = { "claimsOverrideDetails": { "claimsToAddOrOverride": { "attribute_key2": "attribute_value2", "attribute_key": "attribute_value" }, "claimsToSuppress": ["email"] } }; // Return to Amazon Cognito callback(null, event); };

Amazon Cognito passes event information to your Lambda function. The function then returns the same event object back to Amazon Cognito, with any changes in the response. In the Lambda console, you can set up a test event with data that’s relevant to your Lambda trigger. The following is a test event for this code sample:

JSON
JSON
{ "request": {}, "response": {} }

Pre Token Generation Example: Modify the User's Group Membership

This example uses the Pre Token Generation Lambda to modify the user's group membership.

Node.js
Node.js
exports.handler = (event, context, callback) => { event.response = { "claimsOverrideDetails": { "claimsToAddOrOverride": { "attribute_key2": "attribute_value2", "attribute_key": "attribute_value" }, "claimsToSuppress": ["email"], "groupOverrideDetails": { "groupsToOverride": ["group-A", "group-B", "group-C"], "iamRolesToOverride": ["arn:aws:iam::XXXXXXXXXXXX:role/sns_callerA", "arn:aws:iam::XXXXXXXXX:role/sns_callerB", "arn:aws:iam::XXXXXXXXXX:role/sns_callerC"], "preferredRole": "arn:aws:iam::XXXXXXXXXXX:role/sns_caller" } } }; // Return to Amazon Cognito callback(null, event); };

Amazon Cognito passes event information to your Lambda function. The function then returns the same event object back to Amazon Cognito, with any changes in the response. In the Lambda console, you can set up a test event with data that’s relevant to your Lambda trigger. The following is a test event for this code sample:

JSON
JSON
{ "request": {}, "response": {} }