How do I set up email MFA for an Amazon Cognito user pool?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Resolve feature plan error

You can only turn on MFA for emails with the Essentials or Plus feature plan.

If your user pool has the Lite plan and you try to turn on email MFA, then you might receive an error.

In the Amazon Cognito console, you might receive the following error:

"Can't enable email MFA when user pool is not under the Essentials or Plus plan"

If you use the AWS CLI, then you might receive the following error:

"An error occurred (FeatureUnavailableInTierException) when calling the SetUserPoolMfaConfig operation: The following feature is not available for the LITE pricing tier configured: Email MFA"

To resolve the feature plan error, upgrade to the Essentials or Plus feature plan. To change your plan, see Select a feature plan.

Resolve email configuration error

Amazon Cognito uses Amazon Simple Email Service (Amazon SES) to send MFA codes to your user's email address. When you turn on email MFA, you must configure your user pool to use Amazon SES instead of the default email configuration.

If you use the default email configuration, then you might receive an error.

In the Amazon Cognito console, you might receive the following error:

"Can't enable email MFA with email sending in Send email with Cognito configuration"

If you use the AWS CLI, then you might receive the following error:

"An error occurred (InvalidParameterException) when calling the SetUserPoolMfaConfig operation: Cannot set EmailMfaConfiguration when user pool EmailConfiguration contains an EmailSendingAccount of COGNITO_DEFAULT. Update the value of EmailSendingAccount"

To send email MFA codes to your users, set up an Amazon SES account, and then configure Amazon SES with your user pool.

Resolve account recovery error

Amazon Cognito requires separate methods for MFA and account recovery to maintain security. Users must have different channels to receive MFA codes and password reset codes.

Users can't receive MFA and password reset codes at the same email address or phone number. For example, if you configure email for MFA, then your users must use SMS for account recovery. If you try to turn on email MFA without a separate recovery method, then you might receive an error.

In the Amazon Cognito console, you might receive the following error:

"Can't enable email MFA when user pool account recovery method is email-only or legacy."

If you use the AWS CLI, then you might receive the following error:

"An error occurred (InvalidParameterException) when calling the SetUserPoolMfaConfig operation: Cannot set EmailMfaConfiguration when user pool AccountRecoverySetting is not set or contains only verified_email in RecoveryMechanisms. At least one recovery mechanism other than verified_email should be present"

To resolve the error, set up an additional account recovery method. Then, set up email MFA. For instructions, see To set up email MFA in the Amazon Cognito console in Email MFA.

Note: To help users reset their passwords, it's a best practice to set both email and phone_number as required attributes in your user pool.

Related information

Adding MFA to a user pool

Amazon SES email configuration