AWS Logo
Menu
Customize Cognito SMS Sender IDs for Different Tenants

Customize Cognito SMS Sender IDs for Different Tenants

Learn how to send Cognito authentication SMS messages with tenant-specific sender IDs using AWS End User Messaging and Lambda for consistent brand experience

Owen Hawkins
Amazon Employee
Published Feb 4, 2025

The Challenge

I recently worked with a customer who had an interesting challenge: they needed to send SMS notifications through Amazon Cognito using different sender IDs for each of their tenants. Their end users would receive authentication codes and notifications, but the SMS needed to appear as if it came directly from each tenant's brand.
Let me explain what these SMS messages are used for in Cognito. There are three main types of authentication messages:
  • Multi-Factor Authentication (MFA) codes when users sign in
  • Account verification codes when new users sign up
  • Password reset codes when users need to reset their password
In my customer's case, instead of all messages coming from a generic sender ID, they wanted:
  • Tenant A's users to see "COMPANYA: Your code is 123456"
  • Tenant B's users to see "COMPANYB: Your code is 123456"
The solution I developed with them uses Amazon SNS Configuration Sets to route these SMS messages based on the tenant, allowing each one to maintain their unique identity when communicating with their users. I'll share how I implemented this, as it might help others facing similar requirements.

The Solution

I started with the AWS Sample repository https://github.com/aws-samples/amazon-cognito-user-pool-development-and-testing-with-sms-redirected-to-email as my foundation. This sample provided the basic setup for custom SMS handling in Cognito, particularly the KMS key configuration that's crucial for accessing all types of authentication codes.
The KMS key setup is a critical first step because Cognito encrypts all codes before sending them to custom SMS senders. This includes:
  • Account verification codes for new sign-ups
  • Password reset codes for password recovery
  • MFA codes for multi-factor authentication
I used the CloudFormation templates from the sample repository which created:
  • The Cognito User Pool with custom SMS sender Lambda trigger
  • A KMS key with the necessary permissions
  • IAM roles configured to allow the Lambda function to decrypt these codes
  • The basic Lambda function structure for custom SMS sending
I then manually:
  • Added a custom attribute 'senderGroup' to the User Pool to identify different tenants, this could alternatively be your existing tenant ID attribute if you're using one
  • Registered and verified multiple sender IDs in AWS End User Messaging
  • Updated the Lambda environment variables to include these sender IDs
The core of my solution is a Lambda function that uses the custom attribute from the Cognito user's directory to determine which sender ID to use. This attribute could be your existing tenant identifier - there's no need to create a separate attribute if you already have a way to identify the tenant. The function:
  • Decrypts the authentication codes from Cognito using the KMS key specified in the environment variable
  • Reads the user's attributes to determine their tenant
  • Selects the appropriate sender ID based on the tenant
  • Sends the SMS using the End User Messaging API
Here's the implementation:

Results and Benefits

What I particularly like about this approach is its flexibility. While I built this for tenant-specific sender IDs, the same pattern works well for other scenarios - whether you're routing by region, business unit, or message type. The solution leverages attributes already stored in Cognito's user directory, making it easy to adapt for different use cases.
In my customer's case, this solution helped them maintain brand consistency across all authentication-related communications. Whether users are signing up, resetting passwords, or using MFA, they receive SMS messages that appear to come directly from their tenant's brand, which was exactly what they needed. The centralized authentication system through Cognito, combined with tenant-specific messaging, provided both the security and branding requirements they were looking for.
 

Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.

Comments