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

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

These are the parameters that Amazon Cognito passes to this Lambda function along with the event information in the common parameters.

JSON

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

Pre token generation request parameters

groupConfiguration

The input object that contains the current group configuration. The object includes groupsToOverride, iamRolesToOverride, and preferredRole.

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, and preferredRole.

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 the cognito: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.

Node.js

const handler = async (event) => {
  event.response = {
    claimsOverrideDetails: {
      claimsToAddOrOverride: {
        my_first_attribute: "first_value",
        my_second_attribute: "second_value",
      },
      claimsToSuppress: ["email"],
    },
  };

  return event;
};

export { handler };

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.

JSON

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

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.

Node.js

const handler = async (event) => {
  event.response = {
    claimsOverrideDetails: {
      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 event;
};

export { handler };

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:

JSON

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