Customizing user pool workflows with Lambda triggers - Amazon Cognito

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 Custom sender Lambda triggers 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:

  • Except for Custom Sender Lambda triggers, 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.

  • Except for Custom Sender Lambda triggers, errors thrown by Lambda triggers will be visible directly to your end users as query parameters in the Callback URL if they are using Amazon Cognito Hosted UI. 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.

  • When you create a Lambda trigger outside of the Amazon Cognito console, you must add permissions to the Lambda function. This allows Amazon Cognito to invoke the function on behalf of your user pool. You can add permissions from the Lambda Console or use the Lambda AddPermission operation.

    Example Lambda Resource-Based Policy

    The following example Lambda resource-based policy grants Amazon Cognito a limited ability to invoke a Lambda function. Amazon Cognito can only invoke the function when it does so on behalf of both the user pool in the aws:SourceArn condition and the account in the aws:SourceAccount condition.

    { "Version": "2012-10-17", "Id": "default", "Statement": [ { "Sid": "lambda-allow-cognito", "Effect": "Allow", "Principal": { "Service": "cognito-idp.amazonaws.com" }, "Action": "lambda:InvokeFunction", "Resource": "<your Lambda function ARN>", "Condition": { "StringEquals": { "AWS:SourceAccount": "<your account number>" }, "ArnLike": { "AWS:SourceArn": "<your user pool ARN>" } } } ] }

Adding a user pool Lambda trigger

Original console

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

New console

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, and then choose User Pools.

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

  4. Choose the User pool properties tab and locate Lambda triggers.

  5. Choose Add a Lambda trigger.

  6. Select a Lambda trigger Category based on the stage of authentication you wish to customize.

  7. Select Assign Lambda function and select a function in the same AWS Region as your user pool.

    Note

    If your AWS Identity and Access Management credentials have permission to update the Lambda function, Amazon Cognito will add a Lambda resource-based policy that allows Amazon Cognito to invoke the selected function. If the signed-in credentials do not have sufficient IAM permissions, you must update the resource-based policy separately. For more information, see Important considerations

  8. Choose Save changes.

  9. 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:

JSON
{ "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

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.
Pre sign-up PreSignUp_ExternalProvider Pre sign-up for external identity providers.
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.