How do I configure and troubleshoot SAML 2.0 authentication in OpenSearch Service?

Resolution

For information about how to configure SAML 2.0 for OpenSearch Dashboards, see SAML authentication for OpenSearch Dashboards.

If you encounter issues when you set up SAML 2.0 authentication, then take the following troubleshooting actions based on the issue that you encounter.

You receive the "Your request: '/some/path' is not allowed" error

To troubleshoot this issue, make sure that you use the correct single sign-on URL for your IdP.

Also, verify that you use the right URL for your authentication type:

• For Service Provider (SP) initiated authentication, use DashboardsURL/_opendistro/_security/saml/acs.
• For IdP-initiated authentication, use DashboardsURL/_opendistro/_security/saml/acs/idpinitiated.
  Note: Replace DashboardsURL with your domain's OpenSearch Dashboard URL.

You receive the "Please provide valid identity provider metadata document to enable SAML" error

To troubleshoot this issue, take the following actions to validate the metadata XML file from your IdP:

• Use an XML validation tool to check for errors in the metadata XML file. For example, use XML validator on the W3Schools website.
• Verify that the metadata conforms to the SAML 2.0 standard. For more information, see Security Assertion Markup Language (SAML) V2.0 technical overview on the Oasis website.
• Confirm that you included all the required elements in the metadata XML file.

If you update the file, then complete the following steps to update the metadata in your OpenSearch Service SAML 2.0 configuration:

1. Open the OpenSearch Service console.
2. Choose Domains.
3. Select your domain.
4. Choose Domain details.
5. Choose Edit security configuration.
6. Under SAML authentication, choose Edit.
7. Upload or enter the updated metadata.
8. Choose Save changes.

The SAML 2.0 configuration options don't appear in the AWS Management Console

This issue occurs when you use an outdated version of OpenSearch Service software.

To check your software version, complete the following steps:

1. Open the OpenSearch Service console.
2. Choose Domains.
3. Select your domain.
4. Check your OpenSearch Service software version. If you use a previous version, then initiate a service software update.
5. Refresh your browser, and then check for the SAML 2.0 configuration options.

If you still encounter issues, then open an AWS Support case.

You receive the "SAML configuration error: Something went wrong while retrieving the SAML configuration, please check your settings" error

To troubleshoot the "SAML configuration error" error, check for configuration issues.

Check your SP entity ID and single sign-on URL

Check the SP entity ID and single sign-on URL in your IdP configuration.

Then, complete the following steps to check your OpenSearch Service domain configuration:

1. Open the OpenSearch Service console.
2. Choose Domains.
3. Select your domain.
4. Choose Domain details.
5. Choose Edit security configuration.
6. Check the SP entity ID and single sign-on URL values. The IdP configuration must use the values in the OpenSearch Service domain. If needed, then update your IdP configuration.

Check your IdP metadata file

Complete the following steps:

1. Generate the metadata file from your IdP.
2. Open the OpenSearch Service console.
3. Choose Domains.
4. Select your domain.
5. Choose Domain details.
6. Choose Edit security configuration.
7. Under SAML authentication, make sure that values in the security configuration match the IdP entity ID in the metadata file. If they don't match, then choose Edit, and then upload or update the metadata.
8. Choose Save changes.

Check your domain access policy

Make sure that your domain access policy allows access to OpenSearch Dashboards and to the _plugins/_security/* endpoints.

Example policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "es:ESHttp*",
      "Resource": [
        "arn:aws:es:region:account-id:domain/domain-name/_dashboards*",
        "arn:aws:es:region:account-id:domain/domain-name/_plugins/_security/*",
        ...
      ]
    }
  ]
}

Note: Replace region with your AWS Region, account-id with your AWS account ID, and domain-name with your domain name. For domains that you activated fine-grained access control, it's a best practice to use an open access policy.

Check the documentation for your IdP

Check the documentation for your IdP for additional required SAML 2.0 configuration steps.

You receive the "Missing role: No roles available for this user, please contact your system administrator" error

This error typically occurs when you successfully authenticate but didn't map the username or backend roles from the SAML 2.0 assertion to any roles.

To troubleshoot this issue, complete the following steps.

1. To view your SAML 2.0 assertion, install a browser extension such as SAML-tracer on the Firefox website or SAML-tracer on the Chrome web store website.
2. In the SAML 2.0 assertion, check the following settings:
   Verify that the username in the IdP matches the value of the Subject Key element in the SAML 2.0 assertion. For example, if the Subject Key is Email, then check the value of the Email element in the SAML 2.0 assertion. If there's no Subject Key element, then the username is the value for NameID.
   Verify that the backend roles in the IdP match the value of the Roles Key element in the SAML 2.0 assertion. For example, if Roles Key is Group, then check for the value of the Group element in the SAML 2.0 assertion. Typically the backend role is Group or User.
3. Log in to OpenSearch Dashboards as an admin user, and then run the following command to check the existing role mappings:

   GET _plugins/_security/api/rolesmapping

   In the output, check whether the role mapping matches the username and backend role in the SAML assertion. If the mappings don't match, then proceed to the next step.
4. Use the username or backend role from the SAML 2.0 to create new role mappings. To map a user or backend role to an internal role in OpenSearch, see Mapping users to roles on the OpenSearch website.
   Important: Role mappings are case-sensitive. Make sure to exactly match the values in the SAML 2.0 assertion.

Your browser redirects or receives HTTP 500 errors when you try to access OpenSearch Dashboards

This issue typically occurs when you have role configuration issues.

To troubleshoot this issue, take the following actions:

• Check whether your roles use too many characters in the SAML 2.0 assertion.
  Note: OpenSearch versions 2.5 and earlier have a maximum quota of 1,500 characters.
• Reduce the number of roles that you assign to users in your IdP configuration.
• If possible, upgrade to OpenSearch version 2.7 or higher.
  Note: Newer versions of OpenSearch increase the maximum quota for SAML 2.0 assertions to 5,000 characters.
• Assign roles based on groups instead of individual roles.
• Check your browser's cookies storage quota, and then clear the cookies if needed.

You can't log out of ADFS

If your metadata file has the <SingleLogoutService/> element, then you can't log out of Microsoft Active Directory Federation Service (ADFS).

To troubleshoot this issue, complete the following steps:

1. Download the IdP metadata XML file from your ADFS server.
2. Open the XML file in a text editor.
3. Remove the entire <SingleLogoutService /> element.
4. Save the file.
5. Open the OpenSearch Service console.
6. Choose Domains.
7. Select your domain.
8. Choose Domain details.
9. Choose Edit security configuration.
10. Under SAML authentication, choose Edit.
11. Upload or enter the updated metadata.
12. Choose Save changes.

You receive the "Could not find entity descriptor for __PATH__" error

The entity ID in the SAML 2.0 response must match the entity ID in the SAML 2.0 metadata in OpenSearch Service. If it doesn't, then you receive the "Could not find entity descriptor" error message.

To troubleshoot this issue, complete the following steps:

1. Activate Amazon CloudWatch error logs for your OpenSearch Service domain.
2. Check the logs immediately after a failed authentication attempt to search for the mismatched value. For example, in Could not find entity descriptor for _PATH_, the mismatched value is _PATH_.
3. Open your IdP configuration to understand the reason for the mismatch. Check the entity ID that's mentioned in the error message.
4. Update the IdP entity ID field in the SAML 2.0 metadata file to exactly match the value from your IdP.
   -or-
   Update your IdP configuration to match the value in the SAML 2.0 metadata that you used to configure SAML 2.0 in OpenSearch Service.

You receive the "Signature validation failed. SAML response rejected" error

This error typically occurs when the signing certificate in your IdP metadata has expired or been rotated.

To troubleshoot this issue, complete the following steps:

1. Contact your IdP administrator to obtain the current signing certificate.
2. Download the signing certificate metadata XML file.
3. Open the OpenSearch Service console.
4. Choose your domain.
5. Choose Domain details.
6. Choose Edit security configuration.
7. Under SAML authentication, choose Edit.
8. Upload or enter the updated metadata.
9. Choose Save changes, and then wait for the domain status to change from PROCESSING to ACTIVE.

You receive the "__PATH__ is not a valid audience for this response" error

This error occurs when the audience in the SAML 2.0 response from your IdP doesn't match the audience that OpenSearch Service expects.

To troubleshoot this issue, complete the following steps:

1. Check the error logs in Amazon CloudWatch Logs for your OpenSearch Service domain to check information about the mismatched value. For example, in _PATH_ is not a valid audience, the mismatched value is _PATH_.
2. Open the OpenSearch Service console.
3. Choose your domain.
4. Choose Domain details.
5. Choose Edit security configuration.
6. Under SAML authentication, note the Service provider entity ID value. In your IdP configuration, check the Audience or SP entity ID setting to make sure that it exactly matches the Service provider entity ID value.
7. If you use custom endpoints, then make sure that Audience matches your custom endpoint URL.
8. Save the changes in your IdP configuration.

Your browser receives an HTTP 400 error with "Invalid Request Id" in the response

This issue typically occurs when you use IdP-initiated single sign-on, but configured the domain with SAML 2.0 and the SP-initiated single sign-on URL.

To resolve this issue, complete the following steps:

1. Open your IdP configuration settings.
2. For SSO URL or ACS URL, change the URL format from DashboardsURL/_opendistro/_security/saml/acs to DashboardsURL/_opendistro/_security/saml/acs/idpinitiated.
   Note: Replace DashboardsURL with your domain's OpenSearch Dashboard URL.
3. Save the configuration changes, and then test the IdP-initiated single sign-on.

You receive the "The response was received at __PATH__ instead of __PATH__" or "The response has an InResponseTo attribute, while no InResponseTo was expected" error message

These errors occur when the Destination configuration in the IdP is incorrect.

To troubleshoot this issue, complete the following steps:

1. In your IdP configuration, check the SSO URL or ACS URL setting.
2. Update the Destination field based on how you configured single sign-on:
   For SP-initiated single sign-on, set the destination to DashboardsURL/_opendistro/_security/saml/acs
   For IdP-initiated flows, set the destination to DashboardsURL/_opendistro/_security/saml/acs/idpinitiated
   Note: Replace DashboardsURL with your domain's OpenSearch Dashboard URL.
3. Save your IdP configuration.
4. Test your single sign-on authentication method.

Related information

Building SAML federation for OpenSearch Service with Okta