Configuring verification and invitation messages
With Amazon Cognito, you can customize SMS and email verification messages and user invitation messages, to enhance the security and user experience of your application. With Amazon Cognito, you can choose between code-based or one-click link verifications to suit your application's needs. This topic discusses how you can personalize multi-factor authentication (MFA) and verification communications in the Amazon Cognito console.
In the Messaging tab under Message templates, you can customize:
-
Your SMS text message multi-factor authentication (MFA) message
-
Your SMS and email verification messages
-
The verification type for email—code or link
-
Your user invitation messages
-
FROM and REPLY-TO email addresses for emails going through your user pool
Note
The SMS and email verification message templates only appear if you have chosen to require phone number and email verification in the Verifications tab. Similarly, the SMS MFA message template only appears if the MFA setting is required or optional.
Topics
Message templates
You can use message templates to insert placeholders into your messages. Amazon Cognito replace the placeholders with the corresponding values. You can reference Universal template placeholders in message templates of any type, although these values won't be present in all message types.
Universal template placeholders | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description |
Token |
Message type | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Verification code | {####} |
Verification, confirmation, and MFA messages | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Temporary password | {####} |
Forgot-password and invitation messages | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
User name | {username} |
Invitation and advanced security messages |
One of the available automated responses with advanced security features is to notify the user that Amazon Cognito detected potentially-malicious activity. You can use advanced security template placeholders to do the following:
-
Include specific details about an event such as IP address, city, country, sign-in time, and device name. Amazon Cognito advanced security features can analyze these details.
-
Verify whether a one-click link is valid.
-
Use event ID, feedback token, and user name to build your own one-click link.
Note
To generate one-click links and use the {one-click-link-valid}
and
{one-click-link-invalid}
placeholders in advanced security email templates, you
must already have a domain configured for your user pool.
Advanced security features add the following placeholders that you can insert into message templates:
Advanced security template placeholders | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description |
Token |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
IP address | {ip-address} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
City | {city} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Country | {country} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Log-in time | {login-time} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Device name | {device-name} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
One-click link is valid | {one-click-link-valid} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
One-click link is not valid | {one-click-link-invalid} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Event ID | {event-id} |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Feedback token | {feedback-token} |
Customizing the SMS message
Note
In the new Amazon Cognito console experience, you can customize SMS messages
You can customize the SMS message for multi-factor authentication (MFA) in the Messaging tab under the Message templates heading.
Important
Your custom message must contain the {####}
placeholder. This placeholder is
replaced with the authentication code before the message is sent.
Amazon Cognito imposes a maximum length for SMS messages, including the authentication code, at 140 UTF-8 characters.
Customizing SMS verification messages
You can customize the SMS message for phone number verifications by editing the template under the Do you want to customize your SMS verification messages? heading.
Important
Your custom message must contain the {####}
placeholder. This placeholder
is replaced with the verification code before the message is sent.
The maximum length for the message, including the verification code, is 140 UTF-8 characters.
Customizing email verification messages
To verify the email address of a user in your user pool with Amazon Cognito, you can send the user an email message with a link that they can select, or you can send them a code that they can enter.
To customize the email subject and message content for email address verification messages, edit the Verification message template in the Messaging tab of your user pool. You can choose a Verification type of Code or Link when you edit your Verification message template.
When you choose Code as the verification type, your custom message must
contain the {####}
placeholder. When you send the message, the verification code
replaces this placeholder.
When you choose Link as the verification type, your custom message must
include a placeholder in the format {##Verify Your Email##}
. You can change the
text string between the placeholder characters, for example {##Click here##}
. A
verification link titled Verify Your Email replaces this
placeholder.
The link for an email verification message directs your user to a URL like the following example.
https://
<your user pool domain>
/confirmUser/?client_id=abcdefg12345678
&user_name=emailtest
&confirmation_code=123456
The maximum length for the message, including the verification code (if present), is 20,000 UTF-8 characters. You can use HTML tags in this message to format the contents.
Customizing user invitation messages
You can customize the user invitation message that Amazon Cognito sends to new users by SMS or email message by editing the Invitation messages template in the Messaging tab.
Important
Your custom message must contain the {username}
and {####}
placeholders. When Amazon Cognito sends the invitation message, it replaces these placeholders with
your user's user name and password.
The maximum length of an SMS message, including the verification code, is 140 UTF-8 characters. The maximum length of an email message, including the verification code, is 20,000 UTF-8 characters. You may use HTML tags in your email messages to format the contents.
Customizing your email address
By default, Amazon Cognito sends email messages to users in your user pools from the address no-reply@verificationemail.com. You can choose to specify custom FROM and REPLY-TO email addresses instead of no-reply@verificationemail.com.
To customize the FROM and REPLY-TO email addresses
-
Navigate to the Amazon Cognito console
, and choose User Pools. -
Choose an existing user pool from the list, or create a user pool.
-
Choose the Messaging tab. Under Email, choose Edit.
-
Choose an SES Region.
-
Choose a FROM email address from the list of email addresses you have verified with Amazon SES in the SES Region you selected. To use an email address from a verified domain, configure email settings in the AWS Command Line Interface or the AWS API. For more information, see Verifying email addresses and domains in Amazon SES in the Amazon Simple Email Service Developer Guide.
-
Choose a Configuration set from the list of configuration sets in your chosen SES Region.
-
Enter a friendly FROM sender name for your email messages, in the format
John Stiles <johnstiles@example.com>
. -
To customize the REPLY-TO email address, enter a valid email address in the REPLY-TO email address field.
Authorizing Amazon Cognito to send Amazon SES email on your behalf (from a custom FROM email address)
You can configure Amazon Cognito to send email from a custom FROM email address instead of its default address. To use a custom address, you must give Amazon Cognito permission to send email message from an Amazon SES verified identity. In most cases, you can grant permission by creating a sending authorization policy. For more information, see Using sending authorization with Amazon SES in the Amazon Simple Email Service Developer Guide.
When you configure a user pool to use Amazon SES for email messages, Amazon Cognito creates the
AWSServiceRoleForAmazonCognitoIdpEmailService
role in your account to grant
access to Amazon SES. No sending authorization policy is needed when the
AWSServiceRoleForAmazonCognitoIdpEmailService
service-linked role is used. You
only need to add a sending authorization policy when you use both the default email
functionality in your user pool and a verified Amazon SES identity
as the FROM address.
For more information about the service-linked role that Amazon Cognito creates, see Using service-linked roles for Amazon Cognito.
The following example sending authorization policy grants Amazon Cognito a limited ability to use an
Amazon SES verified identity. Amazon Cognito can only send email messages when it does so on behalf of
both the user pool in the aws:SourceArn
condition and the
account in the aws:SourceAccount
condition. For more examples,
see Amazon SES sending
authorization policy examples in the
Amazon Simple Email Service Developer Guide.
Note
In this example, the "Sid" value is an arbitrary string that uniquely identifies the statement. For more information about policy syntax, see Amazon SES sending authorization policies in the Amazon Simple Email Service Developer Guide.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "stmnt1234567891234", "Effect": "Allow", "Principal": { "Service": [ "email.cognito-idp.amazonaws.com" ] }, "Action": [ "SES:SendEmail", "SES:SendRawEmail" ], "Resource": "
<your SES identity ARN>
", "Condition": { "StringEquals": { "aws:SourceAccount": "<your account number>
" }, "ArnLike": { "aws:SourceArn": "<your user pool ARN>
" } } } ] }
The Amazon Cognito console adds a similar policy for you when you select an Amazon SES identity from the drop-down menu. If you use the CLI or API to configure the user pool, you must attach a policy structured like the previous example to your Amazon SES Identity.