Secure Your Clusters with SAML

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

Before You Begin

The steps in this section require an understanding of SAML, specifically the SAML 2.0 Web Browser SSO Profile. To learn more about SAML, see:

Configure Your Cluster to Use SAML

You must edit your cluster configuration, sometimes also referred to as the deployment plan, to point to the SAML IdP before you can complete the configuration in Kibana.

  1. Create or use an existing deployment that includes a Kibana instance version 6.4 or later.
  2. Copy the Kibana endpoint URL.
  3. Update your Elasticsearch user settings for the saml realm and specify your IdP provider configuration:

    xpack:
      security:
        authc:
          realms:
            cloud-saml: 
              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"

    You must use the SAML realm name cloud-saml.

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

    Defines the SAML attribute 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, such as https://idpurl.com/sso/saml/metadata.

    The SAML EntityID of your IdP. This can be read from the configuration page of the IdP, or its SAML metadata, such as https://idpurl.com/entity_id.

    Replace KIBANA_ENDPOINT_URL with the one noted in the previous step, such as sp.entity_id: https://eddac6b924f5450c91e6ecc6d247b514.us-east-1.aws.found.io:9243/ including the slash at the end.

  4. The following request is an example how to map an elasticadmin group to the superuser role:

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

    The mapping name

    The Elastic Stack role to map to

    A rule specifying the SAML role to map from

  5. Update Kibana in the user settings configuration to use SAML as the authentication provider:

    xpack.security.authProviders: [saml]
    server.xsrf.whitelist: [/api/security/v1/saml]
    xpack.security.public:
      protocol: https
      hostname: eddac6b924f5450c91e6ecc6d247b514.us-east-1.aws.found.io 
      port: 9243

    The hostname from your Kibana endpoint URL

After completing these steps, you can log into Kibana by authenticating against your SAML IdP.