SAML troubleshooting

Most identity providers (IdPs) allow you to configure multiple authentication methods for different applications. For example, in Okta, these clients are called “Applications.” In Keycloak, they are called “Clients.” Each one has its own entity ID. Make sure to configure to match those settings:

Check the SAML assertion consumer service URL

After a successful login, your IdP sends a SAML response using HTTP POST to OpenSearch Dashboards’s “assertion consumer service URL” (ACS).

The endpoint the OpenSearch Dashboards security plugin provides is:

Make sure that you have configured this endpoint correctly in your IdP. Some IdPs also require you to add all endpoints to the allow list that they send requests to. Ensure that the ACS endpoint is listed.

OpenSearch Dashboards also requires you to add this endpoint to the allow list. Make sure you have the following entry in opensearch_dashboards.yml:

Keycloak

Role settings

Including user roles in the SAML response is dependent on your IdP. For example, in Keycloak, this setting is in the Mappers section of your client. In Okta, you have to set group attribute statements. Make sure this is configured correctly and that the roles_key in the SAML configuration matches the role name in the SAML response:

saml:
  ...
  http_authenticator:
    type: 'saml'
    config:
      ...
      roles_key: Role

If you are not sure what the SAML response of your IdP contains and where it places the username and roles, you can enable debug mode in the log4j2.properties:

This setting prints the SAML response to the OpenSearch log file so that you can inspect and debug it. Setting this logger to debug generates many statements, so we don’t recommend using it in production.

Another way of inspecting the SAML response is to monitor network traffic while logging in to OpenSearch Dashboards. The IdP uses HTTP POST requests to send Base64-encoded SAML responses to:

Check role mapping

The security plugin uses a standard role mapping to map a user or backend role to one or more Security roles.

For username, the security plugin uses the NameID attribute of the SAML response by default. For some IdPs, this attribute does not contain the expected username, but some internal user ID. Check the content of the SAML response to locate the element you want to use as username, and configure it by setting the :

For checking that the correct backend roles are contained in the SAML response, inspect the contents, and set the correct attribute name:

saml:
  ...
  http_authenticator:
    type: 'saml'
    challenge: true
    config:
      ...

The security plugin trades the SAML response for a more lightweight JSON web token. The username and backend roles in the JWT are ultimately mapped to roles in the security plugin. If there is a problem with the mapping, you can enable the token debug mode using the same setting as Inspect the SAML response.

This setting prints the JWT to the OpenSearch log file so that you can inspect and debug it using a tool like .