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

I need to troubleshoot errors users might encounter when they federate into Amazon Cognito with Security Assertion Markup Language 2.0 (SAML 2.0).

ResolutionAmazon Cognito supports authentication with identity providers (IdPs) and SAML 2.0. There are common errors that users might encounter when federating into Amazon Cognito using SAML.Note: Throughout, replace <attribute_name> with the user attribute from your error scenario.View SAML responsesTo resolve common SAML federation errors, look at the SAML response sent from the IdP to the Amazon Cognito user pool. For instructions on how to capture and decode the SAML response, see viewing a SAML response in your browser.Note: The SAMLResponse element contains the base64-encoded request. A payload that has % characters indicates that the payload is URL-encoded in addition to base64. Perform URL decoding on the SAMLResponse value before sending it for base64 decoding.Resolve invalid SAML response errors"Invalid SAML response received: Invalid user attributes: <attribute_name>: The attribute is required."This error occurs when a user pool is configured with required attributes but the IdP isn't passing claims for required attributes. This error also occurs when attribute mapping isn't available for required attributes.Follow these steps to resolve the error:1.    Open the Amazon Cognito console.2.    Select your user pool.3.    Review the information about the user pool. Note the required attributes configured under Sign-up experience.4.    Retrieve and review the SAML response in your browser.5.    Check whether the IdP is passing all the required attribute claims in the response's AttributeStatement field. If the IdP isn't sending all required attributes in the SAML response, review your IdP's attribute mapping configuration. Make sure that your IdP is configured to send the correct mappings for required attributes.Note: Your IdP might offer sample SAML assertions for reference. You can check the assertions to obtain more details about the IdP's mapped attributes. Some IdPs use simple names for attribute mappings, such as an email address, while others use URL-formatted attribute names similar to this example:http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress6.    When the SAML response includes required attributes but you're still getting the same error, check the Amazon Cognito attribute mappings. When a mapping is missing for a required attribute, add a mapping to the attribute claim. For instructions on how to add attribute mappings, see Specifying identity provider attribute mappings for your user pool."Invalid SAML response received: Invalid user attributes: <attribute_name>: Required attribute cannot be deleted."This error occurs when a required attribute is changed in the IdP so that the required attribute is null or deleted. This error also occurs when a mapping is removed after a user is created.Follow these steps to resolve the error:1.    Open the Amazon Cognito console.2.    Select your Amazon Cognito user pool.3.    Review the information about the user pool. Note the configured required attributes.4.    Retrieve and review the SAML response in your browser.5.    Check whether the IdP is passing all required attribute claims in the response's AttributeStatement field. If the IdP isn't sending all required attributes in the SAML response, then review the IdP's attribute mapping configuration. Make sure that your IdP is set up to send required attributes with the correct mappings.6.    If all required attributes are passed with valid values in the SAML response, then check the IdP attribute mappings. Make sure that there are mappings for all required attributes.Note: You might encounter the following error during federation requests after an IdP's required attribute is deleted or changed to null: "Invalid SAML response received: Invalid user attributes: <attribute_name>: Required attribute cannot be deleted." This error also occurs when the mapping is removed after a user is created. To resolve this error, follow the previous steps to make sure that the mapping exists for required attributes. Then a correct value is passed for your required attributes from your IdP."Invalid SAML response received: Invalid user attributes: <attribute_name>: Attribute cannot be updated."This error occurs when an attribute is passed from the IdP but the mapped Amazon Cognito attribute is set to be immutable ("mutable" : "false"). You can't change an attribute's mutability settings after a user pool is created. To resolve this error, you need to remove the attribute mappings rule that maps the SAML attribute to an immutable attribute.Follow these steps to resolve the error:1.    Run the following AWS Command Line Interface (AWS CLI) command and note the attributes returned in the output. All the attributes returned in the output are immutable.Note: Replace <userpool_id> with your user pool ID.aws cognito-idp describe-user-pool --user-pool-id <userpool_id> --query 'UserPool.SchemaAttributes[?Mutable==`false`].Name'Note: If you receive errors when running AWS CLI commands, make sure that you're using the most recent version of the AWS CLI.2.    Open the Amazon Cognito console.3.    Review the SAML attribute mappings for your provider.4.    Check whether any of the SAML attributes are mapped to Amazon Cognito attributes returned in the command output. If there's a mapping to an immutable attribute, delete that mapping. If you're required to have that SAML attribute mapped, map it to any existing mutable attribute. You can also create a custom mutable attribute and map the SAML attribute to the custom mutable attribute.There's no workaround that you can perform on an existing user pool to delete a mapping because a mapped attribute is required. You must create a new user pool with the required mutability settings and migrate your users to the new user pool."Invalid SAML response received: SAML Response signature is invalid."This error occurs when the IdP changes the SAML signing certificate. To troubleshoot this issue, review the SAML response you receive when you federate into Amazon Cognito. Note the value given in the X509Certificate field. Compare this X509Certificate value in the SAML response with the X509Certificate value in the metadata XML file uploaded to Amazon Cognito for the IdP configuration. If the values are different, then it means the SAML signing certificate used by the IdP is updated.Follow these steps to resolve the error:1.    Navigate to your IdP's application configuration page and then fetch the updated metadata file.2.    Open the Amazon Cognito console.3.    Navigate to the configuration for your SAML IdP.4.    Replace the existing metadata file with the updated metadata file.-or-If your IdP offers SAML metadata through a public URL, then copy the metadata document URL. Paste that public URL instead of uploading a metadata file."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."Note: The error message differs based on the IdP.This error occurs when you incorrectly configure your entity ID on your IdP. This error also occurs when you use another user pool's URN as the entity ID.Follow these steps to resolve the error:1.    Open the Amazon Cognito console.2.    Choose User pools and then note your user pool ID.3.    Go to the IdP's SAML application settings and then configure the entity ID in the following format:Note: Replace <user_pool_id> with your Amazon Cognito user pool ID.urn:amazon:cognito:sp:<user_pool_id>"An error was encountered with the requested page."This error occurs on the Amazon Cognito Hosted UI page. When this error message isn't accompanied by any other error statements, it indicates that your application's Assertion Consumer Service (ACS) URL is configured incorrectly. Your IdP uses the ACS URL to send a SAML response to Amazon Cognito. The ACS URL follows this format:Note: Replace <your_user_pool_domain> with your user pool domain.https://<your_user_pool_domain>/saml2/idpresponseAmazon Cognito only supports POST binding for the endpoint. Your IdP must send SAML responses in the POST request to the endpoint. If you incorrectly configure this URL on your IdP's application, then your IdP sends the SAML response to an incorrect endpoint. This results in a 400 error and a federation failure.Follow these steps to resolve the error:1.    Go to your IdP's application configuration and set the ACS URL by using one of the following formats:Cognito domain:https://<your_user_pool_domain>.auth.<region>.amazoncognito.com/saml2/idpresponseCustom domain:https://<your_user_pool_domain>/saml2/idpresponse"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."This error occurs for the following reasons:The RelayState parameter is set to null by the IdP when a SAML response is sent to Amazon Cognito.The ACS URL in the SAML request isn't the same as the ACS URL configured in your IdP's application.Amazon Cognito generates a RelayState parameter when forwarding an authentication request to your IdP. This RelayState parameter must be returned by the IdP to Amazon Cognito after successfully authenticating.During SAML federation, a user pool acts as a service provider on behalf of your application. As a service provider, Amazon Cognito only supports service provider-initiated single-sign-on (SSO) flows. IdP-initiated flows aren't supported. When a federation request is initiated from your IdP, the IdP's required attribute is deleted or changed to null. A federation failure is the result that includes the error message previously mentioned.To resolve this error, initiate the federation request from Amazon Cognito instead of the IdP. To initiate federation from Amazon Cognito, take either of the following steps to start your authentication flow:Redirect users to the /login endpoint for signing in. The /login endpoint loads the login page and presents the client authentication options to users. Connect to the /login endpoint when users need to check different options to sign in to your applications and get redirected to the IdP.Send requests to the /oauth2/authorize endpoint for Amazon Cognito. The /oauth2/authorize endpoint is a redirection endpoint that supports two redirect destinations. When you include an identity_provider or idp_identifier parameter in the URL, your user is seamlessly redirected to the sign-in page for the IdP. You might use this option to skip the default layout of the hosted UI and to get directly redirected to the IdP page.The error also occurs when the ACS URL is different when a federation request for the same IdP application is from a different user pool. Follow these steps to investigate and resolve the error:1.    When you federate into Amazon Cognito, capture the HTTP Archive (HAR) file.2.    In your browser, on the Network tab, look for the request with a saml?SamlRequest entry and then open the request.3.    Copy the SAMLRequest provided in the request parameters.4.    Use your preferred SAML decoding tool to decode the SAMLRequest. Then, check whether the ACS URL sent in the SAMLRequest is the same as the one that's set on your IdP's application.The error is confirmed when the SAMLRequest values are different.5.    To resolve the error, check your IdP configuration. Make sure that the ACS URL set on your application is the same as the ACS URL sent in the SAMLRequest.The ACS URL is different when a federation request is generated for the same IdP application from a different user pool. Make sure that you start your federation request from the appropriate user pool.