Customizing User Pool Workflows with Lambda Triggers - Amazon Cognito
AWS services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with AWS services in China.

Customizing User Pool Workflows with Lambda Triggers

You can create an AWS Lambda function and then trigger that function during user pool operations such as user sign-up, confirmation, and sign-in (authentication) with a Lambda trigger. You can add authentication challenges, migrate users, and customize verification messages.

The following table summarizes some of the customizations that can be made:

User Pool Flow Operation Description

Custom Authentication Flow

Define Auth Challenge Determines the next challenge in a custom auth flow
Create Auth Challenge Creates a challenge in a custom auth flow
Verify Auth Challenge Response Determines if a response is correct in a custom auth flow
Authentication Events Pre Authentication Lambda Trigger Custom validation to accept or deny the sign-in request
Post Authentication Lambda Trigger Event logging for custom analytics
Pre Token Generation Lambda Trigger Augment or suppress token claims
Sign-Up Pre Sign-up Lambda Trigger Custom validation to accept or deny the sign-up request
Post Confirmation Lambda Trigger Custom welcome messages or event logging for custom analytics
Migrate User Lambda Trigger Migrate a user from an existing user directory to user pools
Messages Custom Message Lambda Trigger Advanced customization and localization of messages
Token Creation Pre Token Generation Lambda Trigger Add or remove attributes in Id tokens
Email and SMS third-party providers Pre Token Generation Lambda Trigger Use a third-party provider to send SMS and email messages

Important Considerations

The following information is important to consider before you start working with Lambda functions:

  • Amazon Cognito invokes Lambda functions synchronously. When called, your Lambda function must respond within 5 seconds. If it does not, Amazon Cognito retries the call. After 3 unsuccessful attempts, the function times out. This 5-second timeout value cannot be changed. For more information see the Lambda programming model.

  • If you delete an AWS Lambda trigger, you must update the corresponding trigger in the user pool. For example, if you delete the post authentication trigger, you must set the Post authentication trigger in the corresponding user pool to none.

  • Errors thrown by Lambda triggers will be visible directly to your end users if they are using Amazon Cognito Hosted UI as query parameters in the Callback URL. As a recommended best practice, end user facing errors should be thrown from the Lambda triggers and any sensitive or debugging information should be logged in the Lambda trigger itself.

Adding a User Pool Lambda Trigger

To add a user pool Lambda trigger with the console

  1. Create a Lambda function using the Lambda console. For more information on Lambda functions, see the AWS Lambda Developer Guide.

  2. Navigate to the Amazon Cognito console, choose Manage User Pools.

  3. Choose an existing user pool from the list, or create a user pool.

  4. In your user pool, choose the Triggers tab from the navigation bar.

  5. Choose a Lambda trigger such as Pre sign-up or Pre authentication and choose your Lambda function from the Lambda function drop-down list.

  6. Choose Save changes.

  7. You can log your Lambda function using CloudWatch in the Lambda console. For more information see Accessing CloudWatch Logs for Lambda.

User Pool Lambda Trigger Event

Amazon Cognito passes event information to your Lambda function which returns the same event object back to Amazon Cognito with any changes in the response. This event shows the Lambda trigger common parameters:

{ "version": "string", "triggerSource": "string", "region": AWSRegion, "userPoolId": "string", "userName": "string", "callerContext": { "awsSdkVersion": "string", "clientId": "string" }, "request": { "userAttributes": { "string": "string", .... } }, "response": {} }

User Pool Lambda Trigger Common Parameters


The version number of your Lambda function.


The name of the event that triggered the Lambda function. For a description of each triggerSource see User Pool Lambda Trigger Sources.


The AWS Region, as an AWSRegion instance.


The user pool ID for the user pool.


The username of the current user.


The caller context, which consists of the following:


The AWS SDK version number.


The ID of the client associated with the user pool.


The request from the Amazon Cognito service. This request must include:


One or more pairs of user attribute names and values. Each pair is in the form "name": "value".


The response from your Lambda trigger. The return parameters in the response depend on the triggering event.

User Pool Lambda Trigger Sources

This section describes each Amazon Cognito Lambda triggerSource parameter, and its triggering event.

Sign-up, confirmation, and sign-in (authentication) triggers
Trigger triggerSource value Triggering event
Pre sign-up PreSignUp_SignUp Pre sign-up.
Pre sign-up PreSignUp_AdminCreateUser Pre sign-up when an admin creates a new user.
Post confirmation PostConfirmation_ConfirmSignUp Post sign-up confirmation.
Post confirmation PostConfirmation_ConfirmForgotPassword Post Forgot Password confirmation.
Pre authentication PreAuthentication_Authentication Pre authentication.
Post authentication PostAuthentication_Authentication Post authentication.
Custom authentication challenge triggers
Trigger triggerSource value Triggering event
Define auth challenge DefineAuthChallenge_Authentication Define Auth Challenge.
Create auth challenge CreateAuthChallenge_Authentication Create Auth Challenge.
Verify auth challenge VerifyAuthChallengeResponse_Authentication Verify Auth Challenge Response.
Pre token generation triggers
Trigger triggerSource value Triggering event
Pre token generation TokenGeneration_HostedAuth Called during authentication from the Amazon Cognito hosted UI sign-in page.
Pre token generation TokenGeneration_Authentication Called after user authentication flows have completed.
Pre token generation TokenGeneration_NewPasswordChallenge Called after the user is created by an admin. This flow is invoked when the user has to change a temporary password.
Pre token generation TokenGeneration_AuthenticateDevice Called at the end of the authentication of a user device.
Pre token generation TokenGeneration_RefreshTokens Called when a user tries to refresh the identity and access tokens.
Migrate user triggers
Trigger triggerSource value Triggering event
User migration UserMigration_Authentication User migration at the time of sign in.
User migration UserMigration_ForgotPassword User migration during the forgot-password flow.
Custom message triggers
Trigger triggerSource value Triggering event
Custom message CustomMessage_SignUp Custom message – To send the confirmation code post sign-up.
Custom message CustomMessage_AdminCreateUser Custom message – To send the temporary password to a new user.
Custom message CustomMessage_ResendCode Custom message – To resend the confirmation code to an existing user.
Custom message CustomMessage_ForgotPassword Custom message – To send the confirmation code for Forgot Password request.
Custom message CustomMessage_UpdateUserAttribute Custom message – When a user's email or phone number is changed, this trigger sends a verification code automatically to the user. Cannot be used for other attributes.
Custom message CustomMessage_VerifyUserAttribute Custom message – This trigger sends a verification code to the user when they manually request it for a new email or phone number.
Custom message CustomMessage_Authentication Custom message – To send MFA code during authentication.