Creating the CustomSMS Trigger in AWS Cognito using lambda

AWS Cognito
Official Document → https://aws.amazon.com/about-aws/whats-new/2014/07/10/introducing-amazon-cognito/

The aws doc provide a sufficient information to create the custom trigger but some generic details were missing, due to which i decided to record everything in this doc for future reference.
There will be two part for this tutorial
1. Creating a userpool, and configuring it with phone number validation using sms
2. Creating custom sms lambda trigger.

Part 1

Lets create a userpool from the UI,
Create the new userpool using step through settings,

Create New Userpool

For the Attributes choose phone numbers as required attribute and allow phone number as username.

Attributes Settings

The policies can be left as default for now, you can always change it later, moving to the MFA and verification, since we are going to use phone number as our primary username, so it is obvious that we need to turn the MFA as optional and use sms text message as second factors, we are going to use phone number to recover the password as well, do not worry about the MFA part as we are not going to verify through MFA for each login attempt by the user, all we need is to verify the user’s phone number when he/she signup to the applications.

MFA and verification settings

After configuring as shown above you do need to create a new IAM role, do not worry about the sns part as we are not going to use it, we will replace the default sns with our custom sms provider.

Create new IAM role

Now create an app client,

App Client Create

After this let everything be default and create the userpool.

Part 2

Creating the custom sms trigger
Official doc → https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-sender-triggers.html
https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-sms-sender.html

Create a Custom Lambda Function

Creating lambda from scratch

Lambda Code to be uploaded

Add the index.js and node_modules folder in a zip and upload to the created lambda function. There some env values such as ENCRIPTION_KEY_ARN and CUSTOM_SMS_* which we can add later from configuration > enviroment variables.

enviroment variables for lambda

Create a new Symmetric encryption key from KMS.

Symmetric Key Creation

Do not forget to add the lambda iam in the key user

giving permission to lambda to use the key

then finally update the key arn value into the lambda env variables.

Grant Amazon Cognito service principal cognito-idp.amazonaws.com access to invoke the Lambda function

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

Update user pool to add custom sender Lambda triggers

aws cognito-idp update-user-pool --user-pool-id userpool-id --lambda-config "CustomSMSSender={LambdaVersion=V1_0,LambdaArn= lambda-arn },KMSKeyID= key-id"

after executing the above step it will reset the MFA, so we need to re-configure it like in part 1 and then we are good to go.

Bonus:

To test the setting create a new App Client settings and launch the hosted UI and signup new user.

App Client Settings

Hosted UI for Cognito

SMS Code (Working)