Customizing user pool workflows with Lambda triggers

The events that Amazon Cognito sends to your Lambda triggers might change with new features. The positions of response and request elements in the JSON hierarchy might change, or element names might be added. In your Lambda function, you can expect to receive the input-element key-value pairs described in this guide, but stricter input validation can cause your functions to fail.

You can choose one of multiple versions of the events that Amazon Cognito sends to some triggers. Some versions might require you to accept a change to your Amazon Cognito pricing. For more information about pricing, see Amazon Cognito Pricing. To customize access tokens in a Pre token generation Lambda trigger, you must configure your user pool with advanced security features and update your Lambda trigger configuration to use event version 2.

Except for Custom sender Lambda triggers, Amazon Cognito invokes Lambda functions synchronously. When Amazon Cognito calls your Lambda function, it must respond within 5 seconds. If it doesn't and if the call can be retried, Amazon Cognito retries the call. After three unsuccessful attempts, the function times out. You can't change this five-second timeout value. For more information, see Lambda programming model in the Amazon Lambda Developer Guide.

Amazon Cognito doesn't retry function calls that return an Invoke error with an HTTP status code of 500-599. These codes indicate a configuration issue that leaves Lambda unable to launch the function. For more information, see Error handling and automatic retries in Amazon Lambda.

You can't declare a function version in your Lambda trigger configuration. Amazon Cognito user pools invoke the latest version of your function by default. However, you can associate a function version with an alias and set your trigger LambdaArn to the alias ARN in a CreateUserPool or UpdateUserPool API request. This option isn't available in the Amazon Web Services Management Console. For more information about aliases, see Lambda function aliases in the Amazon Lambda Developer Guide.

If you delete a 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.

If your Lambda function doesn't return the request and response parameters to Amazon Cognito, or returns an error, the authentication event doesn't succeed. You can return an error in your function to prevent a user's sign-up, authentication, token generation, or any other stage of their authentication flow that invokes Lambda trigger.

The Amazon Cognito hosted UI returns errors that Lambda triggers generate as error text above the sign-in prompt. The Amazon Cognito user pools API returns trigger errors in the format [trigger] failed with error [error text from response]. As a best practice, only generate errors in your Lambda functions that you want your users to see. Use output methods like print() to log any sensitive or debugging information to CloudWatch Logs. For an example, see Pre sign-up example: Deny sign-up if user name has fewer than five characters.

You can add a Lambda function in another Amazon Web Services account as a trigger for your user pool. You must add cross-account triggers with the CreateUserPool and UpdateUserPool API operations, or their equivalents in Amazon CloudFormation and the Amazon CLI. You can't add cross-account functions in the Amazon Web Services Management Console.

When you add a Lambda trigger in the Amazon Cognito console, Amazon Cognito adds a resource-based policy to your function that permits your user pool to invoke the function. When you create a Lambda trigger outside of the Amazon Cognito console, including a cross-account function, you must add permissions to the resource-based policy of the Lambda function. Your added permissions must allow 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 API 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>"
                }
            }
        }
    ]
}