How do I troubleshoot MFA error messages in my Amazon Cognito user pool?

Resolution

Troubleshoot SMS MFA errors

"InvalidSmsRoleAccessPolicyException" error

This error occurs when the AWS Identity and Access Management (IAM) role doesn't have permission to use Amazon SNS to publish SMS text messages.

To resolve this issue, complete the following steps to add the sns:Publish permission to the IAM role:

1. Open the Amazon Cognito console.
2. In the navigation pane, choose User pools.
3. Select your user pool.
4. In the navigation pane, under Authentication, choose Authentication methods.
5. In the SMS section, note the name for IAM role ARN.
6. Open the IAM console.
7. In the navigation pane, choose Roles.
8. In the search bar, enter your IAM role's name, and then select your IAM role.
9. In the Permissions policies section, select the policy that's attached to the IAM role.
10. On the Policy details page, choose Edit to add the sns:publish permission.
11. Choose Next.
12. Choose Save changes.
13. Verify that a service control policy (SCP) doesn't block the sns:Publish action.

"InvalidSmsRoleTrustRelationshipException" error

This error occurs when the IAM role doesn't have a 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's trust policy doesn't match what's in the user pool's SMS configuration.

To resolve this issue, correctly configure the trust policy for the IAM role. For instructions, see Prepare an IAM role that Amazon Cognito can use to send SMS messages with AWS End User Messaging SMS.

"InvalidParameterException" error

This error occurs when the API request sends an invalid parameter to Amazon Cognito. To resolve this issue, specify all required values in the SetUserPoolMfaConfig API's SmsMfaConfiguration parameter.

Troubleshoot TOTP MFA errors

Requirements:

• Add MFA to your user pool before you configure the time-based one-time password (TOTP) software token.
• If Amazon Cognito didn't authenticate your users, then your users must try to sign in to your application before you can associate TOTP tokens with them.

Note: External identity providers (IdPs) manage MFA for federated users. Amazon Cognito doesn't prompt for MFA during user federation.

"NotAuthorizedException: Access token does not have required scopes" error

This error occurs when the access token doesn't include the required aws.cognito.signin.user.admin scope to call the AssociateSoftwareToken API. When a user uses the InitiateAuth API to sign in, the InitiateAuth API automatically includes this scope in the access token.

However, when a user uses the managed login page to sign in, verify that the access token includes the aws.cognito.signin.user.admin scope. To check if the token includes the aws.cognito.signin.user.admin scope, decode the payload of the access token with Base64. For more information, see Confirm the structure of the JWT.

If the token doesn't include the aws.cognito.signin.user.admin scope, complete the following steps to add it:

1. Open the Amazon Cognito console.
2. In the navigation pane, choose User Pools.
3. Select the user pool that you want to modify.
4. In the navigation pane, under Applications, choose App clients.
5. Select the app client that you want to modify.
6. Choose the Login pages tab, and then choose Edit.
7. On the OpenID Connect scopes dropdown list, choose aws.cognito.signin.user.admin.
8. Choose Save changes.

"NotAuthorizedException: Invalid session for the user, session can only be used once" error

This error occurs when a user tries to use reuse a session. If users receive this error in the middle of an authentication flow with TOTP MFA, then they must restart the authentication process from the beginning. To restart the authentication, use the InitiateAuth API or AdminInitiateAuth API.

"NotAuthorizedException: Invalid session for the user, session is expired" error

This error occurs when the session expires. By default, sessions expire after 3 minutes.

To resolve this issue, increase the authentication session flow duration in your app client. You can increase the duration up to 15 minutes.

"CodeMismatchException: Invalid code or auth state for the user" error

This error occurs when the user's TOTP code isn't valid, the user's state doesn't support the API call, or the TOTP code expired. For example, a user calls the RespondToAuthChallenge API with an MFA_SETUP challenge and didn't configure TOTP MFA.

To resolve this issue, complete the following steps:

1. Configure TOTP MFA for the user.
2. Call the RespondToAuthChallenge API with the MFA_SETUP challenge.
3. Verify that your user device's time settings match the current time to generate valid TOTP codes.

"InvalidParameterException: User does not have delivery config set to turn on SOFTWARE_TOKEN_MFA" error

This error occurs when a you didn't configure TOTP MFA for your users. To resolve the issue, configure TOTP MFA before you call the SetUserMFAPreference API or AdminSetUserMFAPreference API.

"SoftwareTokenMFANotFoundException: Software Token MFA has not been enabled by the userPool" error

This error occurs because you didn't configure TOTP MFA in your user pool. To resolve the error, configure TOTP MFA.

"NotAuthorizedException: Invalid session for the use" error

This error occurs for the following reasons:

• An API call includes an incorrect session string.
• API calls don't occur in the correct sequence.

To resolve this issue, configure API calls in the correct sequence. For example, to receive the session string in the response, first call the InitiateAuth API. To prevent an issue, verify that the next API call uses the returned session string in its request parameter.

"EnableSoftwareTokenMFAException: Code mismatch" error

This error occurs when the TOTP code that the user submits doesn't match what Amazon Cognito expects during TOTP MFA configuration.

To resolve this issue, take the following actions:

• Retrieve the secret code from the AssociateSoftwareToken API.
• Save the secret code in the authenticator application.
• Submit an up-to-date TOTP code.
• Use the secret code that you retrieved from the AssociateSoftwareToken API to generate a QR code. Then, use the following code sample to configure your authenticator application.

Example of Python code to generate a QR code from the secret code:

import pyotp
from qrcode.main import QRCode

secret_key = "secret-key-retrieved-from-associate-software-token-api"

totp = pyotp.TOTP(secret_key)
provisioning_uri = totp.provisioning_uri()

qr = QRCode()
qr.add_data(provisioning_uri)
qr.make()
qr.print_ascii()

Troubleshoot email MFA errors

Before you set up email as an MFA factor, you must configure Amazon Simple Email Service (Amazon SES) in your user pool to send email messages to your users.

When you activate MFA and choose email as the second factor, Amazon Cognito sends email messages to an unverified email address. After users complete the email message MFA verification, Amazon Cognito sets the email_verified attribute to true.

"InvalidParameterException: Cannot set EmailMfaConfiguration when user pool EmailConfiguration contains an EmailSendingAccount of COGNITO_DEFAULT" error

This error occurs when you use default email configuration. To resolve this issue, configure Amazon SES email settings for your user pool.

"InvalidParameterException: Cannot set EmailMfaConfiguration when user pool AccountRecoverySetting is not set or contains only verified_email in RecoveryMechanisms" error

This error occurs when you use only email for the user's account recovery method. You can't use the same factor in both MFA and account recovery. To resolve this issue, choose a different account recovery method instead of email. For instructions, see Configure password reset and recovery.

"FeatureUnavailableInTierException" error

This error occurs when your user pool has the Lite feature plan. Only the Essentials and Plus plan includes email MFA. To resolve this issue, switch your user pool's plan to Essentials or Plus.

Related information

Adding MFA to a user pool

SMS and email message MFA