Amazon Cognito
Developer Guide

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.

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.

Important

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.

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:

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

User Pool Lambda Trigger Common Parameters

version

The version number of your Lambda function.

triggerSource

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

region

The AWS Region, as an AWSRegion instance.

userPoolId

The user pool ID for the user pool.

userName

The username of the current user.

callerContext

The caller context, which consists of the following:

awsSdkVersion

The AWS SDK version number.

clientId

The ID of the client associated with the user pool.

request

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

userAttributes

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

response

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.