Configuring Multi-Factor Authentication (MFA) for Amazon Cognito User Pools
In the MFA and verifications tab, you can choose settings for multi-factor authentication (MFA).
Multi-factor authentication (MFA) increases security for your app by adding an authentication method and not relying solely on username (or alias) and password.
The following MFA settings are available:
-
Required: All users must use MFA. This setting can only be specified when your user pool is created.
-
Optional: Individual users can choose whether to enable MFA for their own user accounts.
-
Off: MFA is disabled for all users.
SMS Text Message MFA
When a user signs in with MFA turned on, he or she first enters and submits his or
her
username and password. The client app will receive a getMFA response indicating
where the authorization code was sent. The client app should indicate to the user
where to
look for the code (such as which phone number the code was sent to), provide a form
for
entering the code, and then submit the code to complete the sign-in process. The destination
is masked (e.g., only the last 4 digits of the phone number are displayed). If an
app is
using the Amazon Cognito hosted UI, it shows a page for the user to enter the MFA
code.
The SMS text message authorization code is valid for 3 minutes.
If a user no longer has access to his or her device where the SMS text message MFA codes are sent, he or she must request help from your customer service office. An administrator with necessary AWS account permissions can change the user's phone number, but only via the AWS Command Line Interface or the API.
When a user successfully goes through the SMS text message MFA flow, his or her phone number is also marked as verified.
Note
SMS for MFA is charged separately. (There is no charge for sending verification codes to email addresses.) For information about Amazon SNS pricing, see Worldwide SMS Pricing. For the current list of countries where SMS messaging is available, see Supported Regions and Countries.
Important
To ensure that SMS messages are sent to verify phone numbers and for SMS text message MFA, you must request an increased spend limit from Amazon SNS.
Amazon Cognito uses Amazon SNS for sending SMS messages to users. The number of SMS messages Amazon SNS delivers is subject to spend limits. Spend limits can be specified for an AWS account and for individual messages, and the limits apply only to the cost of sending SMS messages.
The default spend limit per account (if not specified) is 1.00 USD per month. If you want to raise the limit, submit an SNS Limit Increase case in the AWS Support Center. For New limit value, enter your desired monthly spend limit. In the Use Case Description field, explain that you are requesting an SMS monthly spend limit increase.
TOTP Software Token MFA
Your user is challenged to complete authentication using a time-based one-time (TOTP) password after their username and password have been verified when TOTP software token MFA is enabled. If your app is using the Amazon Cognito hosted UI to sign in users, the UI will show a second page for your user to enter the TOTP password after they have submitted their username and password.
You can enable TOTP MFA for your user pool in the Amazon Cognito console, through the Amazon Cognito hosted UI, or using Amazon Cognito APIs. At the user pool level, you can configure MFA and enable TOTP MFA by calling SetUserPoolMfaConfig.
Note
If TOTP software token MFA is not enabled for the user pool, users can't associate
or
verify with the token and will receive a SoftwareTokenMFANotFoundException
exception, as follows: "Software Token MFA has not been enabled by the userPool."
Configuring TOTP for your user is a multi-step process where your user receives a secret code that he or she validates by entering a one-time password . Next, you can enable TOTP MFA for your user or set TOTP as the preferred MFA method for your user.
Associate the TOTP Token
-
When your user chooses TOTP software token MFA, call AssociateSoftwareToken to return a unique generated shared secret key code for the user account. The request for this API method takes an access token or a session string, but not both. As a convenience, you can distribute the secret key as a quick response (QR) code.
-
The key code or QR code appears on your app and your user needs to enter it into a TOTP-generating app such as Google Authenticator.
-
Your user enters the key code into the TOTP-generating app to associate a new account with your client app.
Verify the TOTP Token
-
After a new TOTP account is associated with your app, it will generate a temporary password.
-
Your user enters the temporary password into your app, which responds with a call to VerifySoftwareToken. On the Amazon Cognito service server, a TOTP code is generated and compared with your user's temporary password. If they match, then the service marks it as verified.
-
If the code is correct, check that the time used is in the range and within the maximum number of retries. If your user passes all of the steps, the verification is complete.
Or, if the code is wrong, the verification cannot be finished and your user can either try again or cancel. We recommend that your user sync the time of their TOTP-generating app.
Sign-in with TOTP MFA
-
Your user enters username and password to sign in to your client app.
-
The TOTP MFA challenge is invoked and your user is prompted by your app to enter a temporary password.
-
Your user gets the temporary password from an associated TOTP-generating app.
-
Your user enters the TOTP code into your client app. Your app notifies the Amazon Cognito service to verify it. For each sign-in, RespondToAuthChallenge should be called to get a response to the new TOTP authentication challenge.
-
If the token is verified by Amazon Cognito, the sign-in is successful and your user continues with the authentication flow.
Remove the TOTP Token
-
Your app should allow your user to remove the TOTP token.
-
Your client app should ask your user to enter his or her password.
-
If the password is correct, remove the TOTP token.
Note
A delete TOTP software token operation is not currently available in the API. This functionality is planned for a future release. Use SetUserMFAPreference to disable TOTP MFA for an individual user.
