How do I troubleshoot invalid SAML response errors that users receive when they federate into Amazon Cognito?

Resolution

Review SAML responses

In your browser, review the SAML response that your identity provider (IdP) sent to Amazon Cognito.

Note: The SAMLResponse element contains a base64-encoded response. If you see percentage (%) characters in the payload, then the response is URL-encoded and base64-encoded. In this case, perform URL decoding on the SAMLResponse value, and then apply base64 decoding.

Check your attribute mappings

"The attribute is required"

You receive the following error message:

"Invalid SAML response received: Invalid user attributes: <attribute_name>: The attribute is required"

To resolve this issue, complete the following steps:

1. Open the Amazon Cognito console.
2. In the navigation pane, choose User pools, and then select your user pool.
3. Under Sign-up experience, note the required attributes that you configured.
4. Check whether you configured attribute mappings for your user pool. If you didn't map your attributes, then specify attribute mappings.
5. Retrieve the SAML response in your browser.
6. In the AttributeStatement field, verify whether the IdP includes the required attributes.
7. In your IdP's attribute mapping configuration, confirm that you set up your IdP to send the required attributes with the correct mappings.

Note: Your IdP might use simple names for attribute mappings, such as an email address or a URL format. An example of a URL-formatted attribute name is http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.

"Required attribute cannot be deleted"

You receive the following error message:

"Invalid SAML response received: Invalid user attributes: <attribute_name>: Required attribute cannot be deleted"

This error occurs when the IdP sets a required attribute to null, deletes a required attribute, or removes an attribute mapping after user creation.

To resolve this issue, map all the required attributes and configure the IdP to send correct values for the attributes.

For more information, see Things to know about mappings.

Check for immutable attributes

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.

You receive the following error message:

"Invalid SAML response received: Invalid user attributes: <attribute_name>: Attribute cannot be updated"

This error occurs when the IdP passes an attribute that's mapped to an immutable Amazon Cognito attribute. After you create a user pool, you can't change the attribute mutability.

To resolve this issue, complete the following steps:

1. Run the following describe-user-pool command:

   aws cognito-idp describe-user-pool --user-pool-id USER-POOL-ID --query 'UserPool.SchemaAttributes[?Mutable==`false`].Name'

   Note: Replace USER-POOL-ID with your user pool ID.
2. In the command's output, note all the immutable attributes.
3. Open the Amazon Cognito console.
4. In the SAML attribute mappings for your IdP, check whether your SAML attributes map to the Amazon Cognito immutable attributes. If a SAML attribute maps to an immutable attribute, then delete the mapping.
   Note: If you must map the SAML attribute, then map it to an existing mutable attribute. You can also create a custom mutable attribute that you can map to the SAML attribute.

If you require a mapped attribute, then create a new user pool with correct mutability settings and import your users into the new user pool.

Compare the values between your SAML response and the IdP metadata XML file

You receive the following error message:

"Invalid SAML response received: SAML Response signature is invalid"

This error occurs when your IdP updates its SAML signing certificate. The update creates a mismatch between the X509Certificate values in your SAML response and IdP metadata XML file.

To resolve this issue, complete the following steps:

1. Download the latest metadata file on your IdP's application configuration page.
   Note: If your IdP offers SAML metadata through a public URL, then you can note the metadata document URL and enter the public URL.
2. Open the Amazon Cognito console.
3. In your SAML IdP's configuration settings, replace the existing metadata file with the new metadata file.

Check the entity ID and URN

You receive one of the following error messages:

"Invalid SAML response received: Audience restriction in SAML Assertion does not allow it for urn:amazon:cognito:sp:xxxxxxxx"

-or-

"Invalid SAML response received: Application with identifier 'urn:amazon:cognito:sp:xxxxxxxx' was not found"

These errors occur when you configure an incorrect entity ID in your IdP, or use another user pool's Uniform Resource Name (URN).

To resolve this issue, complete the following steps:

1. Open the Amazon Cognito console.
2. In the navigation pane, choose User pools, and then select the user pool you want to configure for SAML integration.
3. In the navigation pane, choose Overview, and then note your user pool ID.
4. In the IdP's SAML application settings, configure the entity ID in the urn:amazon:cognito:sp:USER-POOL-ID format.
   Note: Replace USER-POOL-ID with your Amazon Cognito user pool ID.

Check your IdP's assertion consumer (ACS) URL configuration

You receive the following error message:

"An error was encountered with the requested page"

You get this error on the Amazon Cognito managed login page when you incorrectly configure your IdP's assertion consumer service (ACS) URL. Amazon Cognito supports only POST binding for the endpoint. Your IdP must send SAML responses in the POST request to the endpoint. If you incorrectly configure the URL on your IdP's application, then your IdP sends the SAML response to an incorrect endpoint.

To resolve this issue, configure your IdP's application with the correct ACS URL format.

An example format for a default Amazon Cognito user pool domain is https://YOUR-USER-POOL-DOMAIN.auth.REGION.amazoncognito.com/saml2/idpresponse.

An example format for a custom user pool domain is https://YOUR-USER-POOL-DOMAIN/saml2/idpresponse.

Note: Replace YOUR-USER-POOL-DOMAIN with your user pool domain.

Confirm the type of sign-in that your IdP supports

You receive one of the following error messages:

"An error was encountered with the requested page: Invalid relayState from identity provider"

-or-

"An error was encountered with the requested page: Invalid samlResponse or relayState from identity provider"

These errors occur in both IdP-initiated and service provider-initiated (SP-initiated) SAML sign-in flows for the following reasons:

• The IdP set the RelayState parameter to null in the SAML response to Amazon Cognito.
• You used the same IdP application with a different user pool. As a result, the ACS URL in the SAML request doesn't match the ACS URL in your IdP's application configuration.

Note: For SP-initiated SAML sign-in flows, Amazon Cognito includes a RelayState parameter in the authentication request to your IdP. After authentication, your IdP must return the RelayState parameter to Amazon Cognito. For IdP-initiated SAML sign-in flows, your IdP must include a RelayState parameter with the SAML assertion to the /saml2/idpresponse endpoint.

To resolve RelayState issues, determine whether your SAML IdP supports only SP-initiated SAML sign-in or both IdP-initiated and SP-initiated SAML sign-in.

If your IdP supports SP-initiated SAML sign-in flows, then start your authentication flow from Amazon Cognito to initiate the federation request. You can use the /login managed login endpoint that redirects users to the sign-in endpoint. Or, use the /oauth2/authorize redirect and authentication endpoint.

If your IdP supports IdP-initiated SAML sign-in flows, then configure your SAML IdP with the RelayState parameter in the identity_provider=ID-PROVIDER-NAME&client_id=CLIENT-ID&redirect_uri=CALLBACK-URL&response_type=code&scope=openid+email+phone format.

Note: Replace ID-PROVIDER-NAME with your SAML IdP's name. Also, replace CLIENT-ID with the app client ID for your user pool and CALLBACK-URL with the callback URL for your app client ID.

To resolve ACS URL issues, complete the following steps:

1. Create an HTTP Archive (HAR) file.
2. In your browser, on the Network tab, locate the request with a saml?SamlRequest entry.
3. Note the SAMLRequest from the request parameters.
4. Use your preferred SAML decoding tool to decode the SAMLRequest.
5. Compare the ACS URL in the decoded request with the one in your IdP configuration.

If the URLs differ, then update your IdP configuration to match the ACS URL in the SAMLRequest. Then, initiate the federation request from the correct user pool.