Custom SMS sender Lambda trigger - Amazon Cognito

Custom SMS sender Lambda trigger

When you assign a custom SMS sender trigger to your user pool, Amazon Cognito invokes a Lambda function instead of its default behavior when a user event requires that it send an SMS message. With a custom sender trigger, your AWS Lambda function can send SMS notifications to your users through a method and provider that you choose. The custom code of your function must process and deliver all SMS messages from your user pool.


Currently, you can't assign custom sender triggers in the Amazon Cognito console. You can assign a trigger with the LambdaConfig parameter in a CreateUserPool or UpdateUserPool API request.

To set up this trigger, perform the following steps:

  1. Create a symmetric encryption key in AWS Key Management Service (AWS KMS). Amazon Cognito generates secrets—temporary passwords, verification codes, and confirmation codes—then uses this KMS key to encrypt the secrets. You can then use the Decrypt API operation in your Lambda function to decrypt the secrets and send them to the user in plaintext. The AWS Encryption SDK is a useful tool for AWS KMS operations in your function.

  2. Create a Lambda function that you want to assign as your custom sender trigger. Grant kms:Decrypt permissions for your KMS key to the Lambda function role.

  3. Grant Amazon Cognito service principal access to invoke the Lambda function.

  4. Write Lambda function code that directs your messages to custom delivery methods or third-party providers. To deliver your user's verification or confirmation code, Base64 decode and decrypt the value of the code parameter in the request. This operation produces a plaintext code or password that you must include in your message.

  5. Update the user pool so that it uses a custom sender Lambda trigger. The IAM principal that updates or creates a user pool with a custom sender trigger must have permission to create a grant for your KMS key. The following LambdaConfig snippet assigns custom SMS and email sender functions.

    "LambdaConfig": { "KMSKeyID": "arn:aws:kms:us-east-1:123456789012:key/a6c4f8e2-0c45-47db-925f-87854bc9e357", "CustomEmailSender": { "LambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction", "LambdaVersion": "V1_0" }, "CustomSMSSender": { "LambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction", "LambdaVersion": "V1_0" }

Custom SMS sender Lambda trigger parameters

The request that Amazon Cognito passes to this Lambda function is a combination of the parameters below and the common parameters that Amazon Cognito adds to all requests.

{ "request": { "type": "customSMSSenderRequestV1", "code": "string", "clientMetadata": { "string": "string", . . . }, "userAttributes": { "string": "string", . . . } }

Custom SMS sender request parameters


The request version. For a custom SMS sender event, the value of this string is always customSMSSenderRequestV1.


The encrypted code that your function can decrypt and send to your user.


One or more key-value pairs that you can provide as custom input to the custom SMS sender Lambda function trigger. To pass this data to your Lambda function, you can use the ClientMetadata parameter in the AdminRespondToAuthChallenge and RespondToAuthChallenge API actions. Amazon Cognito doesn't include data from the ClientMetadata parameter in AdminInitiateAuth and InitiateAuth API operations in the request that it passes to the post authentication function.


One or more key-value pairs that represent user attributes.

Custom SMS sender response parameters

Amazon Cognito doesn't expect any additional return information in the response. Your function can use API operations to query and modify your resources, or record event metadata to an external system.

Activating the custom SMS sender Lambda trigger

You can set up a custom SMS sender trigger that uses custom logic to send SMS messages for your user pool. The following procedure assigns a custom SMS trigger, a custom email trigger, or both to your user pool. After you add your custom SMS sender trigger, Amazon Cognito always sends user attributes, including the phone number, and the one-time code to your Lambda function instead of the default behavior that sends an SMS message with Amazon Simple Notification Service.


Amazon Cognito HTML-escapes reserved characters like < (&lt;) and > (&gt;) in your user's temporary password. These characters might appear in temporary passwords that Amazon Cognito sends to your custom email sender function, but don't appear in temporary verification codes. To send temporary passwords, your Lambda function must unescape these characters after it decrypts the password, and before it sends the message to your user.

  1. Create an encryption key in AWS KMS. This key encrypts temporary passwords and authorization codes that Amazon Cognito generates. You can then decrypt these secrets in the custom sender Lambda function and send them to your user in plaintext.

  2. Grant Amazon Cognito service principal access to encrypt codes with the KMS key.

    Apply the following resource-based policy to your KMS key.

    { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "Service": "" }, "Action": "kms:CreateGrant", "Resource": "arn:aws:kms:us-west-2:111222333444:key/1example-2222-3333-4444-999example", "Condition": { "StringEquals": { "aws:SourceAccount": "111222333444" }, "ArnLike": { "aws:SourceArn": "arn:aws:cognito-idp:us-west-2:111222333444:userpool/us-east-1_EXAMPLE" } } }] }
  3. Create a Lambda function for the custom sender trigger. Amazon Cognito uses the AWS encryption SDK to encrypt the secrets, temporary passwords and codes that authorize your users' API requests.

    1. Assign an IAM role to your Lambda function that has, at minimum, kms:Decrypt permissions for your KMS key.

  4. Grant Amazon Cognito service principal access to invoke the Lambda function.

    The following AWS CLI command grants Amazon Cognito permission to invoke your Lambda function:

    aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal
  5. Compose your Lambda function code to send your messages. Amazon Cognito uses AWS Encryption SDK to encrypt secrets before Amazon Cognito sends the secrets to the custom sender Lambda function. In your function, decrypt the secret and process any relevant metadata. Then send the code, your own custom message, and destination phone number to the custom API that delivers your message.

  6. Add the AWS Encryption SDK to your Lambda function. For more information, see AWS Encryption SDK programming languages. To update the Lambda package, complete the following steps.

    1. Export your Lambda function as a .zip file in the AWS Management Console.

    2. Open your function and add the AWS Encryption SDK. For more information and download links, see AWS Encryption SDK programming languages in the AWS Encryption SDK Developer Guide.

    3. Zip your function with your SDK dependencies, and upload the function to Lambda. For more information, see Deploying Lambda functions as .zip file archives in the AWS Lambda Developer Guide.

  7. Update your user pool to add custom sender Lambda triggers. Include a CustomSMSSender or CustomEmailSender parameter in an UpdateUserPool API request. The UpdateUserPool API operation requires all the parameters of your user pool and the parameters that you want to change. If you don't provide all relevant parameters, Amazon Cognito sets the values of any missing parameters to their defaults. As demonstrated in the example that follows, include entries for all Lambda functions that you want to add to or keep in your user pool. For more information, see Updating user pool configuration.

    #Send this parameter in an 'aws cognito-idp update-user-pool' CLI command, including any existing #user pool configurations. --lambda-config "PreSignUp=lambda-arn, \ CustomSMSSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \ CustomEmailSender={LambdaVersion=V1_0,LambdaArn=lambda-arn}, \ KMSKeyID=key-id"

To remove a custom sender Lambda trigger with an update-user-pool AWS CLI, omit the CustomSMSSender or CustomEmailSender parameter from --lambda-config, and include all other triggers that you want to use with your user pool.

To remove a custom sender Lambda trigger with an UpdateUserPool API request, omit the CustomSMSSender or CustomEmailSender parameter from the request body that contains the rest of your user pool configuration.

Code example

The following Node.js example processes an SMS message event in your custom SMS sender Lambda function. This example assumes your function has two environment variables defined.


The alias of the KMS key that you want to use to encrypt and decrypt your users' codes.


The Amazon Resource Name (ARN) of the KMS key that you want to use to encrypt and decrypt your users' codes.

const AWS = require('aws-sdk'); const b64 = require('base64-js'); const encryptionSdk = require('@aws-crypto/client-node'); //Configure the encryption SDK client with the KMS key from the environment variables. const { encrypt, decrypt } = encryptionSdk.buildClient(encryptionSdk.CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT); const generatorKeyId = process.env.KEY_ALIAS; const keyIds = [ process.env.KEY_ARN ]; const keyring = new encryptionSdk.KmsKeyringNode({ generatorKeyId, keyIds }) exports.handler = async (event) => { //Decrypt the secret code using encryption SDK. let plainTextCode; if(event.request.code){ const { plaintext, messageHeader } = await decrypt(keyring, b64.toByteArray(event.request.code)); plainTextCode = plaintext } //PlainTextCode now contains the decrypted secret. if(event.triggerSource == 'CustomSMSSender_SignUp'){ //Send an SMS message to your user via a custom provider. //Include the temporary password in the message. } else if(event.triggerSource == 'CustomSMSSender_ResendCode'){ } else if(event.triggerSource == 'CustomSMSSender_ForgotPassword'){ } else if(event.triggerSource == 'CustomSMSSender_UpdateUserAttribute'){ } else if(event.triggerSource == 'CustomSMSSender_VerifyUserAttribute'){ } else if(event.triggerSource == 'CustomSMSSender_AdminCreateUser'){ } else if(event.triggerSource == 'CustomSMSSender_AccountTakeOverNotification'){ } return; };

Evaluate SMS message capabilities with a custom SMS sender function

A custom SMS sender Lambda function accepts the SMS messages that your user pool would send, and the function delivers the content based on your custom logic. Amazon Cognito sends the Custom SMS sender Lambda trigger parameters to your function. Your function can do what you want with this information. For example, you can send the code to an Amazon Simple Notification Service (Amazon SNS) topic. An Amazon SNS topic subscriber can be an SMS message, an HTTPS endpoint, or an email address.

To create a test environment for Amazon Cognito SMS messaging with a custom SMS sender Lambda function, see amazon-cognito-user-pool-development-and-testing-with-sms-redirected-to-email in the aws-samples library on GitHub. The repository contains AWS CloudFormation templates that can create a new user pool, or work with a user pool that you already have. These templates create Lambda functions and an Amazon SNS topic. The Lambda function that the template assigns as a custom SMS sender trigger, redirects your SMS messages to the subscribers to the Amazon SNS topic.

When you deploy this solution to a user pool, all messages that Amazon Cognito usually sends through SMS messaging, the Lambda function instead sends to a central email address. Use this solution to customize and preview SMS messages, and to test the user pool events that cause Amazon Cognito to send an SMS message. After you complete your tests, roll back the CloudFormation stack, or remove the custom SMS sender function assignment from your user pool.


Don't use the templates in amazon-cognito-user-pool-development-and-testing-with-sms-redirected-to-email to build a production environment. The custom SMS sender Lambda function in the solution simulates SMS messages, but the Lambda function sends them all to a single central email address. Before you can send SMS messages in a production Amazon Cognito user pool, you must complete the requirements shown at SMS message settings for Amazon Cognito user pools.

Custom SMS sender Lambda trigger sources

The following table shows the triggering event for custom SMS trigger sources in your Lambda code.

TriggerSource value Event
CustomSMSSender_SignUp A user signs up and Amazon Cognito sends a welcome message.
CustomSMSSender_ForgotPassword A user requests a code to reset their password.
CustomSMSSender_ResendCode A user requests a new code to confirm their registration.
CustomSMSSender_VerifyUserAttribute A user creates a new email address or phone number attribute and Amazon Cognito sends a code to verify the attribute.
CustomSMSSender_UpdateUserAttribute A user updates an email address or phone number attribute and Amazon Cognito sends a code to verify the attribute.
CustomSMSSender_Authentication A user configured with SMS multi-factor authentication (MFA) signs in.
CustomSMSSender_AdminCreateUser You create a new user in your user pool and Amazon Cognito sends them a temporary password.