Custom email sender Lambda trigger parameters Activating the custom email sender Lambda trigger Custom email sender trigger sources

Custom email sender Lambda trigger

Amazon Cognito invokes the custom email sender trigger so that a third-party provider can send email notifications to your users from your AWS Lambda function code. Amazon Cognito sends email message events as requests to a Lambda function. The custom code of your function must then process and deliver the message.

Note

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

Set up the custom email sender trigger as follows:

Create a Lambda function that you want to assign as your custom email sender trigger.
Create an encryption key in AWS Key Management Service (AWS KMS). Amazon Cognito generates secrets (temporary passwords and authorization codes), then uses this key to encrypt them. You can then use the AWS Encryption SDK in your Lambda function to decrypt the codes and send them to the user in plaintext.
Grant Amazon Cognito service principal cognito-idp.amazonaws.com permission to invoke the Lambda function.
Write Lambda function code that directs your email messages to custom delivery methods or third-party providers.
Update the user pool so that it uses a custom sender Lambda trigger.

Important

When you configure a custom email sender or a custom SMS sender function for your user pool, configure a symmetric AWS KMS key for additional security. Amazon Cognito uses your configured KMS key to encrypt codes or temporary passwords. Amazon Cognito sends the base64 encoded ciphertext to your Lambda functions. For more information, see Symmetric KMS keys.

Custom email sender Lambda trigger parameters

These are the parameters that Amazon Cognito passes to this Lambda function along with the event information in the common parameters.

Custom email sender request parameters

type: The request version. For a custom email sender event, the value of this string is always customEmailSenderRequestV1.
code: The encrypted code that your function can decrypt and send to your user.
clientMetadata: One or more key-value pairs that you can provide as custom input to the custom email 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.
userAttributes: One or more key-value pairs that represent user attributes.

Custom email sender response parameters

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

Activating the custom email sender Lambda trigger

To set up a custom email sender trigger that uses custom logic to send email messages for your user pool, activate the trigger as follows.

Step 1: Create a Lambda function

Create a Lambda function for the custom email sender trigger. Amazon Cognito uses the AWS encryption SDK to encrypt the secrets (temporary passwords or authorization codes).

Step 2: Create an encryption key in AWS KMS

Create an encryption key in AWS KMS. Amazon Cognito uses this key to encrypt 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 the user in plaintext.

Step 3: Grant Amazon Cognito permission to invoke the Lambda function

Use the following command:



        aws lambda add-permission --function-name lambda_arn --statement-id "CognitoLambdaInvokeAccess" --action lambda:InvokeFunction --principal cognito-idp.amazonaws.com

Step 4: Edit the code to use custom sender

Amazon Cognito uses AWS Encryption SDK to encrypt secrets (temporary passwords and authorization codes) before Amazon Cognito sends the secrets to the custom sender Lambda function. Decrypt these secrets before you send them to users. You can choose a custom provider to send the email message. To use the AWS Encryption SDK with your Lambda function, you must package the SDK with your function. For more information, see Installing the AWS encryption SDK for JavaScript. You can also update the Lambda package as follows:

Export the Lambda function package from the console.
Unzip the package.
Add the AWS Encryption SDK to the package. For example, if you are using Node.js, then add the node_modules directory and include the libraries from @aws-crypto/client-node.
Recreate the package.
Update the Lambda function code from the modified directory.

Step 5: Update user pool to add custom sender Lambda triggers

Update the user pool with a CustomEmailSender parameter in an UpdateUserPool API operation. UpdateUserPool requires all the parameters of your user pool as well as 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. For more information, see Updating user pool configuration.



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

To remove a custom email sender Lambda trigger with the AWS CLI, omit the CustomEmailSender parameter from --lambda-config and include all other triggers that you want to use with your user pool. To remove a custom email sender Lambda trigger with an UpdateUserPool API request, remove CustomemailSender from the request body that contains the rest of your user pool configuration. For more information, see Updating a user pool with the Amazon Cognito API or AWS CLI.

The following Node.js example shows how to process an email message event in your custom email sender Lambda function.



            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_ID ];
            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 has the decrypted secret.
            
            if(event.triggerSource == 'CustomEmailSender_SignUp'){
            
            #Send email to end-user using custom or 3rd party provider.
            #Include temporary password in the email.
            
            }else if(event.triggerSource == 'CustomEmailSender_ResendCode'){
            
            }else if(event.triggerSource == 'CustomEmailSender_ForgotPassword'){
            
            }else if(event.triggerSource == 'CustomEmailSender_UpdateUserAttribute'){
            
            }else if(event.triggerSource == 'CustomEmailSender_VerifyUserAttribute'){
            
            }else if(event.triggerSource == 'CustomEmailSender_AdminCreateUser'){
            
            }else if(event.triggerSource == 'CustomEmailSender_AccountTakeOverNotification'){
            
            }
            
            return;
            };

Custom email sender Lambda trigger sources

The following table shows the triggering events for custom email trigger sources in your Lambda code.

`TriggerSource value`	Triggering event
`CustomEmailSender_SignUp`	A user signs up and Amazon Cognito sends a welcome message.
`CustomEmailSender_ForgotPassword`	A user requests a code to reset their password.
`CustomEmailSender_ResendCode`	A user requests a replacement code to reset their password.
`CustomEmailSender_UpdateUserAttribute`	A user updates an email address or phone number attribute and Amazon Cognito sends a code to verify the attribute.
`CustomEmailSender_VerifyUserAttribute`	A user creates a new email address or phone number attribute and Amazon Cognito sends a code to verify the attribute.
`CustomEmailSender_AdminCreateUser`	You create a new user in your user pool and Amazon Cognito sends them a temporary password.
`CustomEmailSender_AccountTakeOverNotification`	Amazon Cognito detects an attempt to take over a user account and sends the user a notification.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Custom sender Lambda triggers

Custom SMS sender Lambda trigger