Secure Your Clusters with SAML

These steps show how you can secure your Elasticsearch clusters and Kibana instances by using a Security Assertion Markup Language (SAML) identity provider (IdP) for cross-domain, single sign-on authentication.

SAML is supported in ECE version 2.0 with Elastic Stack versions 6.4 and later.


The SAML credentials are valid against the deployment, not the ECE platform.

Before You Begin

The steps in this section require an understanding of SAML, specifically the SAML 2.0 Web Browser SSO Profile. You can learn more about how SAML authentication works with the Elastic Stack.

Configure the Cluster to Use SAML

You must edit the deployment plan to point to the SAML IdP before you can complete the configuration in Kibana.

  1. Create or use an existing an deployment with a Kibana instance that is version 6.4 or later.
  2. Copy the Kibana endpoint URL.
  3. (Optional) If your SAML IdP uses custom or self-signed certificates, you must upload the certificates.

    1. Prepare a custom bundle ZIP file that contains your CA certificates inside of a saml folder.

      This bundle allows all Elasticsearch containers to access and trust the same root certificates via ssl.certifcate_authorities settings.

    2. Update your Elasticsearch cluster with the advanced configuration editor to use the bundles you prepared in the previous step. You need to modify the user_bundles JSON attribute similar to the following example:

        "cluster_name": "xxxxxxx",
        "plan": {
          "elasticsearch": {
            "version": "6.4.1",
            "user_bundles": [
                "name": "saml-ca",
                "url": "",
                "elasticsearch_version": "6.4.1"

      The URLs that point to the bundle ZIP file must be accessible to the deployment.

      Remember the file locations where custom bundles get unzipped, you will need them in the next step. Custom bundles get unzipped under the path /app/config/BUNDLE_DIRECTORY_STRUCTURE, where BUNDLE_DIRECTORY_STRUCTURE is the directory structure within the bundle ZIP file itself.

      $ tree .
      └── saml
            └── root.crt

      In our example, the unzipped CA certificate gets placed under /app/config/saml/root.crt.

  4. Update your Elasticsearch user settings for the saml realm and specify your IdP provider configuration.

              type: saml
              order: 2
              attributes.principal:        "nameid:persistent" 
              attributes.groups:           "groups" 
              idp.metadata.path:           "<check with your idp provider>" 
              idp.entity_id:               "<check with your idp provider>" 
              sp.entity_id:                "KIBANA_ENDPOINT_URL/" 
              sp.acs:                      "KIBANA_ENDPOINT_URL/api/security/v1/saml"
              sp.logout:                   "KIBANA_ENDPOINT_URL/logout"
              ssl.verification_mode        "full"
              ssl.certificate_authorities: ["/app/config/saml/root.crt"] 

    Defines which SAML attribute is going to be mapped to the principal (username) of the authenticated user in Kibana. In this case we use the special nameid:persistent which maps the NameID with the urn:oasis:names:tc:SAML:2.0:nameid-format:persistent format from the Subject of the SAML Assertion.

    Defines which SAML attribute gets used for role mapping when configured in Kibana. Common choices are groups or roles. Both attributes.principal and attributes.groups depend on the IdP provider, so be sure to review their documentation.

    The file path or the HTTPS URL where your IdP metadata is available, e.g.

    The SAML EntityID of your IdP. This can be read from the configuration page of the IdP, or its SAML metadata, e.g.

    Replace KIBANA_ENDPOINT_URL with the one noted in previous step, e.g. sp.entity_id: including the slash at the end.

    Required, if you use custom certificate bundle.

  5. Issue the following request to Elasticsearch:

    POST /_xpack/security/role_mapping/saml1_elasticadmin_to_superuser 
       "enabled": true,
        "roles": [ "superuser" ], 
        "rules": { 
            "field": { "groups": "elasticadmin" }
        "metadata": { "version": 1 }

    Name of this mapping

    Elastic Stack role to map to

    Rule specifying the SAML role to map from

  6. Update Kibana in the advanced configuration editor to use SAML as the authentication provider. [saml]
    server.xsrf.whitelist: [/api/security/v1/saml]
      protocol: https
      port: 9243

    This is the hostname from your Kibana endpoint url.

After completing all of the steps defined above, you can log in to Kibana by authenticating against your SAML IdP.


This content focuses on configuring SAML to work with ECE. See the Elastic Stack guide SAML authentication details on roles and attribute mappings.