Custom sender Lambda triggers

Create a symmetric encryption key in AWS Key Management Service (AWS KMS). Amazon Cognito generates secrets—temporary passwords, verification codes, authentication one-time passwords, 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.

The IAM principal that creates or updates your user pool creates a one-time grant against the KMS key that Amazon Cognito uses to encrypt the code. Grant this principal CreateGrant permissions for your KMS key. For this example KMS key policy to be effective, the administrator who updates the user pool must be signed in with an assumed-role session for the IAM role arn:aws:iam::111222333444:role/my-example-administrator-role.

Apply the following resource-based policy, modified for your environment, to your KMS key.

{
    "Version": "2012-10-17",
    "Statement": [
    {
        "Effect": "Allow",
        "Principal": {
            "AWS": "arn:aws:iam::111122223333:role/my-example-administrator-role"
        },
        "Action": "kms:CreateGrant",
        "Resource": "arn:aws:kms:us-west-2:111122223333:key/1example-2222-3333-4444-999example",
        "Condition": {
            "StringEquals": {
               "kms:EncryptionContext:userpool-id": "us-west-2_EXAMPLE"
            }
        }
    },
    {
        "Sid": "Allow Lambda to decrypt",
        "Effect": "Allow",
        "Principal": {
            "AWS": "arn:aws:iam::111122223333:role/my-lambda-function-role"
        },
        "Action": "kms:Decrypt",
        "Resource": "*"
    }]
} 

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 a Lambda execution role that has, at minimum, kms:Decrypt permissions for your KMS key.

2. Compose Lambda function code to send your messages. The input event to your function contains a secret. In your function, decrypt the secret with the AWS Encryption SDK 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.

3. 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.

Grant Amazon Cognito service principal cognito-idp.amazonaws.com 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 cognito-idp.amazonaws.com

Generate an UpdateUserPool API request with a LambdaConfig parameter that adds custom sender Lambda triggers. You can't add triggers of this type in the Amazon Cognito console. Custom sender triggers require LambdaConfig parameters of KMSKeyID and CustomSMSSender or CustomEmailSender (or both).