How do I troubleshoot MFA errors in my Amazon Cognito user pool?
I have multi-factor authentication (MFA) errors that I must resolve in my Amazon Cognito user pool.
When configuring MFA for your Amazon Cognito user pool, you might encounter multiple types of errors. If you set up Short Message Service (SMS) messages for MFA, then review the following sections: Before setting up SMS for MFA and SMS MFA errors. If you set up time-based one-time passwords (TOTP) for MFA, then review the following sections: Before setting up TOTP for MFA and TOTP MFA errors.
Before setting up SMS for MFA
Before you set up SMS as an MFA factor, you must take additional steps to send SMS messages for the first time. For more information, see Setting up SMS messaging for the first time in Amazon Cognito user pools.
When you activate MFA and choose SMS as the second factor, Amazon Cognito can send SMS messages to unverified phone numbers. After users complete the SMS text message MFA verification, Amazon Cognito sets the phone_number_verified attribute to true.
SMS MFA errors
The AWS Identity and Access Management (IAM) role for the SMS configuration doesn't have permission to use Amazon Simple Notification Service (Amazon SNS) to publish.
To resolve this error, make sure to attach the sns:Publish permission to the IAM role. Also, make sure that the service control policies (SCPs) don't block the sns:Publish action.
This error occurs when the IAM role doesn't have a valid trust relationship that allows Amazon Cognito to assume the role. This happens when cognito-idp.amazonaws.com isn't trusted, or the external ID in the role policy doesn't match what's in the user pool's SMS configuration.
To resolve this error, make sure that you correctly configured the trust policy for the IAM role. For more information, see Setting up SMS messaging for the first time in Amazon Cognito user pools.
This error occurs when Amazon Cognito encounters a parameter that's not valid.
To resolve this error, make sure that all the required values are passed to the SetUserPoolMfaConfig API's SmsMfaConfiguration parameter when setting up SMS for MFA.
Before setting up TOTP for MFA
When setting up TOTP software token MFA in your Amazon Cognito user pool, add MFA to your user pool before you configure the TOTP token.
Unless a user is already authenticated, you can't associate TOTP tokens with a user until the user tries to sign in to your application.
MFA doesn't support federated users in a user pool.
TOTP MFA errors
NotAuthorizedException: Access token does not have required scopes
This error occurs when the access token doesn't include the required aws.cognito.signin.user.admin scope. The aws.cognito.signin.user.admin scope is required when calling the AssociateSoftwareToken API. When a user signs in with the InitiateAuth API, the scope is automatically present in the access token. However, when a users uses a hosted UI to sign in, make sure that the aws.cognito.signin.user.admin scope is present in the access token.
NotAuthorizedException: Invalid session for the user, session can only be used once
This error occurs when a users uses the same session more than once. If a user receives this error in the middle of a flow, then the application must restart the flow from the beginning. If the user uses a session string when calling an API, then the user can't use the session again.
NotAuthorizedException: Invalid session for the user, session is expired
This error occurs when the session validity time expires. The session validity time is 3 minutes by default. To resolve this error, change the app client's Authentication flow session duration setting to increase the session validity time to 15 minutes.
CodeMismatchException: Invalid code or auth state for the user
This error occurs when the user's TOTP code isn't valid, or a user's state isn't compatible with calling the API. For example, if a user calls the RespondToAuthChallenge API with a challenge named MFA_SETUP, but you didn't configure TOTP MFA, then the CodeMismatchException error occurs. To resolve this error, make sure that API calls occur in the correct sequence when you set up MFA.
This error also occurs when the user's TOTP code is too old for Amazon Cognito to accept. To resolve this error, make sure that user devices are in sync with the actual time.
InvalidParameterException: User does not have delivery config set to turn on SOFTWARE_TOKEN_MFA
This error occurs when you didn't configure TOTP MFA, and you call APIs to try to enforce TOTP MFA. To resolve this error, before you enforce TOTP for users that use the SetUserMFAPreference API or the AdminSetUserMFAPreference API, configure TOTP MFA for the users.
NotAuthorizedException: Invalid session for the user
This error occurs when a user calls an API and provides a session string that isn't the expected session string. This error also occurs when users aren't making API calls in the correct sequence. To resolve this error, configure the API calls in the appropriate order. For example, to receive the session string in the response, the user calls the InitiateAuth API first. To prevent an error, verify that the next API call uses the returned session string in its request parameter.
EnableSoftwareTokenMFAException: Code mismatch
This error occurs when a user fails to provide the TOTP code that Amazon Cognito expects during the TOTP MFA configuration. To resolve this error, find the secret code that Amazon Cognito gives in the AssociateSoftwareToken API, and save it in the authenticator application. The user must also provide an up-to-date TOTP code from the authenticator application.
SoftwareTokenMFANotFoundException: Software Token MFA has not been enabled by the userPool
This error occurs when you didn't activate TOTP MFA for your user pool. To resolve this error, configure TOTP MFA before trying to enforce it in Amazon Cognito.