Common SAML issues

Some of the common SAML problems are shown below with tips on how to resolve these issues.

  1. Symptoms:

    Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:

    Cannot find any matching realm for [SamlPrepareAuthenticationRequest{realmName=null,
    assertionConsumerServiceURL=https://my.kibana.url/api/security/v1/saml}]

    Resolution:

    Elasticsearch, Kibana and your Identity Provider need all have the same view on what the Assertion Consumer Service URL of the SAML Service Provider is.

    1. Elasticsearch discovers this via the sp.acs setting in your Elasticsearch SAML realm configuration
    2. Kibana constructs this value using the server.host and server.port in kibana.yml. For instance:

      server.host: kibanaserver.org
      server.port: 3456

      These settings would mean that Kibana would construct the Assertion Consumer Service URL as https://kibanaserver.org:3456/api/security/v1/saml. However, if for example, Kibana is behind a reverse proxy and you have configured the following xpack.security.public.* settings:

      xpack.security.public:
        protocol: https
        hostname: kibana.proxy.com
        port: 8080

      These settings would instruct Kibana to construct the Assertion Consumer Service URL as https://kibana.proxy.com:8080/api/security/v1/saml

    3. The SAML Identity Provider is either explicitly configured by the IdP administrator or consumes the SAML metadata that are generated by Elasticsearch and as such contain the same value for the as the one that is configured in the the sp.acs setting in the Elasticsearch SAML realm configuration.

    The error encountered here indicates that the Assertion Consumer Service URL that Kibana has constructed via one of the aforementioned ways (https://my.kibana.url/api/security/v1/saml) is not the one that Elasticsearch is configured with. Note that these two URLs are compared as case-sensitive strings and not as canonicalized URLs.

    Often, this can be resolved by changing the sp.acs URL in elasticearch.yml to match the value that Kibana has constructed. Note however, that the SAML IdP configuration needs to also be adjusted to reflect this change.

    Alternatively, if you think Kibana is using the wrong value for the Assertion Consumer Service URL, you will need to change the configuration in kibana.yml by adjusting either the server.host and server.port to change the URL Kibana listens to or the xpack.security.public.* settings to make Kibana aware about its correct public URL.

  2. Symptoms:

    Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:

    Authentication to realm saml1 failed - Provided SAML response is not valid for realm
    saml/saml1 (Caused by ElasticsearchSecurityException[Conditions [https://some-url-here...]
    do not match required audience [https://my.kibana.url]])

    Resolution:

    We received a SAML response that is addressed to another SAML Service Provider. This usually means that the configured SAML Service Provider Entity ID in elasticsearch.yml (sp.entity_id) does not match what has been configured as the SAML Service Provider Entity ID in the SAML Identity Provider documentation.

    To resolve this issue, ensure that both the saml realm in Elasticsearch and the IdP are configured with the same string for the SAML Entity ID of the Service Provider.

    These strings are compared as case-sensitive strings and not as canonicalized URLs even when the values are URL-like. Be mindful of trailing slashes, port numbers, etc.

  3. Symptoms:

    Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:

    Cannot find metadata for entity [your:entity.id] in [metadata.xml]

    Resolution:

    We could not find the metadata for the SAML Entity ID your:entity.id in the configured metadata file (metadata.xml).

    1. Ensure that the metadata.xml file you are using is indeed the one provided by your SAML Identity Provider.
    2. Ensure that the metadata.xml file contains one <EntityDescriptor> element as follows: <EntityDescriptor ID="0597c9aa-e69b-46e7-a1c6-636c7b8a8070" entityID="https://saml.example.com/f174199a-a96e-4201-88f1-0d57a610c522/" ... where the value of the entityID attribute is the same as the value of the idp.entity_id that you have set in your SAML realm configuration in elasticsearch.yml.
    3. Note that these are also compared as case-sensitive strings and not as canonicalized URLs even when the values are URL-like.
  4. Symptoms:

    Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:

    unable to authenticate user [<unauthenticated-saml-user>]
    for action [cluster:admin/xpack/security/saml/authenticate]

    Resolution:

    This error indicates that Elasticsearch failed to process the incoming SAML authentication message. Since the message can’t be processed, Elasticsearch is not aware of who the to-be authenticated user is and the <unauthenticated-saml-user> placeholder is used instead. To diagnose the actual problem, you must check the Elasticsearch logs for further details.

  5. Symptoms:

    Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:

    Authentication to realm my-saml-realm failed -
    Provided SAML response is not valid for realm saml/my-saml-realm
    (Caused by ElasticsearchSecurityException[SAML Response is not a 'success' response:
    Code=urn:oasis:names:tc:SAML:2.0:status:AuthnFailed Message=null Detail=null])

    Resolution:

    This means that the SAML Identity Provider failed to authenticate the user and sent a SAML Response to the Service Provider (Elastic Stack) indicating this failure. The Code, Message and Detail can convey different error identifiers and additional information that might offer an indication about the cause of the failure. In case Message and Detail are null, please consult the logs and documentation of the Identity Provider in order to further diagnose the problem.

  6. Symptoms:

    Authentication in Kibana fails and the following error is printed in the Elasticsearch logs:

    The XML Signature of this SAML message cannot be validated. Please verify that the saml
    realm uses the correct SAMLmetadata file/URL for this Identity Provider

    Resolution:

    This means that Elasticsearch failed to validate the digital signature of the SAML message that the Identity Provider sent. Elasticsearch uses the public key of the Identity Provider that is included in the SAML metadata, in order to validate the signature that the IdP has created using its corresponding private key. Failure to do so, can have a number of causes:

    1. As the error message indicates, the most common cause is that the wrong metadata file is used and as such the public key it contains doesn’t correspond to the private key the Identity Provider uses.
    2. The configuration of the Identity Provider has changed or the key has been rotated and the metadata file that Elasticsearch is using has not been updated.
    3. The SAML Response has been altered in transit and the signature cannot be validated even though the correct key is used.

    The private keys and public keys and self-signed X.509 certificates that are used in SAML for digital signatures as described above have no relation to the keys and certificates that are used for TLS either on the transport or the http layer. A failure such as the one described above has nothing to do with your xpack.ssl related configuration.

  7. Symptoms:

    Users are unable to login with a local username and password in Kibana because SAML is enabled.

    Resolution:

    If you want your users to be able to use local credentials to authenticate to Kibana in addition to using the SAML realm for Single Sign-On, you must enable the basic authProvider in Kibana. The process is documented in the SAML Guide

Logging:

Very detailed trace logging can be enabled specifically for the SAML realm by setting the following transient setting:

PUT /_cluster/settings
{
  "transient": {
    "logger.org.elasticsearch.xpack.security.authc.saml": "trace"
  }
}

Alternatively, you can add the following lines to the end of the log4j2.properties configuration file in the ES_PATH_CONF:

logger.saml.name = org.elasticsearch.xpack.security.authc.saml
logger.saml.level = TRACE