Configuring SAML single-sign-on on the Elastic Stack

If your Elasticsearch cluster is operating in production mode, then you must configure the HTTP interface to use SSL/TLS before you can enable SAML authentication.

For more information, see Encrypt HTTP client communications for Elasticsearch.

The Elasticsearch SAML implementation makes use of the Elasticsearch Token Service. This service is automatically enabled if you configure TLS on the HTTP interface, and can be explicitly configured by including the following in your elasticsearch.yml file:

xpack.security.authc.token.enabled: true

SAML authentication is enabled by configuring a SAML realm within the authentication chain for Elasticsearch.

This realm has a few mandatory settings, and a number of optional settings. The available settings are described in detail in Security settings. For example, SAML realm settings, SAML realm signing settings, SAML realm encryption settings, SAML realm SSL settings. This guide will walk you through the most common settings.

Create a realm by adding the following to your elasticsearch.yml configuration file. Each configuration value is explained below.

xpack.security.authc.realms.saml.saml1:
  order: 2
  idp.metadata.path: saml/idp-metadata.xml
  idp.entity_id: "https://sso.example.com/"
  sp.entity_id:  "https://kibana.example.com/"
  sp.acs: "https://kibana.example.com/api/security/saml/callback"
  sp.logout: "https://kibana.example.com/logout"
  attributes.principal: "urn:oid:0.9.2342.19200300.100.1.1"
  attributes.groups: "urn:oid:1.3.6.1.4.1.5923.1.5.1."

The configuration values used in the example above are:

When a user connects to Kibana through your Identity Provider, the Identity Provider will supply a SAML Assertion about the user. The assertion will contain an Authentication Statement indicating that the user has successfully authenticated to the IdP and one or more Attribute Statements that will include Attributes for the user.

These attributes may include such things as:

Attributes in SAML are named using a URI such as urn:oid:0.9.2342.19200300.100.1.1 or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn, and have one or more values associated with them.

These attribute identifiers vary between IdPs, and most IdPs offer ways to customize the URIs and their associated value.

Elasticsearch uses these attributes to infer information about the user who has logged in, and they can be used for role mapping (below).

In order for these attributes to be useful, Elasticsearch and the IdP need to have a common value for the names of the attributes. This is done manually, by configuring the IdP and the SAML realm to use the same URI name for each logical user attribute.

The recommended steps for configuring these SAML attributes are as follows:

xpack.security.authc.realms.saml.saml1:
  order: 2
  idp.metadata.path: saml/idp-metadata.xml
  idp.entity_id: "https://sso.example.com/"
  sp.entity_id:  "https://kibana.example.com/"
  sp.acs: "https://kibana.example.com/api/security/saml/callback"
  attributes.principal: "nameid:persistent"
  attributes.groups: "roles"
  nameid_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"

xpack.security.authc.realms.saml.saml1:
  order: 2
  idp.metadata.path: saml/idp-metadata.xml
  idp.entity_id: "https://sso.example.com/"
  sp.entity_id:  "https://kibana.example.com/"
  sp.acs: "https://kibana.example.com/api/security/saml/callback"
  attributes.principal: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  attribute_patterns.principal: "^([^@]+)@staff\\.example\\.com$"

It is sometimes necessary for a SAML SP to be able to impose specific restrictions regarding the authentication that will take place at an IdP, in order to assess the level of confidence that it can place in the corresponding authentication response. The restrictions might have to do with the authentication method (password, client certificates, etc), the user identification method during registration, and other details. Elasticsearch implements SAML 2.0 Authentication Context, which can be used for this purpose as defined in SAML 2.0 Core Specification.

In short, the SAML SP defines a set of Authentication Context Class Reference values, which describe the restrictions to be imposed on the IdP, and sends these in the Authentication Request. The IdP attempts to grant these restrictions. If it cannot grant them, the authentication attempt fails. If the user is successfully authenticated, the Authentication Statement of the SAML Response contains an indication of the restrictions that were satisfied.

You can define the Authentication Context Class Reference values by using the req_authn_context_class_ref option in the SAML realm configuration. See SAML realm settings.

Elasticsearch supports only the exact comparison method for the Authentication Context. When it receives the Authentication Response from the IdP, Elasticsearch examines the value of the Authentication Context Class Reference that is part of the Authentication Statement of the SAML Assertion. If it matches one of the requested values, the authentication is considered successful. Otherwise, the authentication attempt fails.

The SAML protocol supports the concept of Single Logout (SLO). The level of support for SLO varies between Identity Providers. You should consult the documentation for your IdP to determine what Logout services it offers.

By default the Elastic Stack will support SAML SLO if the following are true:

The Elastic Stack supports generating signed SAML messages (for authentication and/or logout), verifying signed SAML messages from the IdP (for both authentication and logout) and can process encrypted content.

You can configure Elasticsearch for signing, encryption or both, with the same or separate keys used for each of those.

The Elastic Stack uses X.509 certificates with RSA private keys for SAML cryptography. These keys can be generated using any standard SSL tool, including the elasticsearch-certutil tool.

Your IdP may require that the Elastic Stack have a cryptographic key for signing SAML messages, and that you provide the corresponding signing certificate within the Service Provider configuration (either within the Elastic Stack SAML metadata file or manually configured within the IdP administration interface). While most IdPs do not expected authentication requests to be signed, it is commonly the case that signatures are required for logout requests. Your IdP will validate these signatures against the signing certificate that has been configured for the Elastic Stack Service Provider.

Encryption certificates are rarely needed, but the Elastic Stack supports them for cases where IdPs or local policies mandate their use.

bin/elasticsearch-certutil cert --self-signed --pem --days 1100 --name saml-sign --out saml-sign.zip

The SAML support in Kibana is designed on the expectation that it will be the primary (or sole) authentication method for users of that Kibana instance. However, it is possible to support both SAML and Basic authentication within a single Kibana instance by setting xpack.security.authc.providers as per the example below:

xpack.security.authc.providers:
  saml.saml1:
    order: 0
    realm: "saml1"
  basic.basic1:
    order: 1

If Kibana is configured in this way, users are presented with a choice at the Login Selector UI. They log in with SAML or they provide a username and password and rely on one of the other security realms within Elasticsearch. Only users who have a username and password for a configured Elasticsearch authentication realm can log in via Kibana login form.

Alternatively, when the basic authentication provider is enabled, you can place a reverse proxy in front of Kibana, and configure it to send a basic authentication header (Authorization: Basic ....) for each request. If this header is present and valid, Kibana will not initiate the SAML authentication process.

If you wish to have multiple Kibana instances that authenticate against the same Elasticsearch cluster, then each Kibana instance that is configured for SAML authentication, requires its own SAML realm.

Each SAML realm must have its own unique Entity ID (sp.entity_id), and its own Assertion Consumer Service (sp.acs). Each Kibana instance will be mapped to the correct realm by looking up the matching sp.acs value.

These realms may use the same Identity Provider, but are not required to.

The following is example of having 3 difference Kibana instances, 2 of which use the same internal IdP, and another which uses a different IdP.

xpack.security.authc.realms.saml.saml_finance:
  order: 2
  idp.metadata.path: saml/idp-metadata.xml
  idp.entity_id: "https://sso.example.com/"
  sp.entity_id:  "https://kibana.finance.example.com/"
  sp.acs: "https://kibana.finance.example.com/api/security/saml/callback"
  sp.logout: "https://kibana.finance.example.com/logout"
  attributes.principal: "urn:oid:0.9.2342.19200300.100.1.1"
  attributes.groups: "urn:oid:1.3.6.1.4.1.5923.1.5.1."
xpack.security.authc.realms.saml.saml_sales:
  order: 3
  idp.metadata.path: saml/idp-metadata.xml
  idp.entity_id: "https://sso.example.com/"
  sp.entity_id:  "https://kibana.sales.example.com/"
  sp.acs: "https://kibana.sales.example.com/api/security/saml/callback"
  sp.logout: "https://kibana.sales.example.com/logout"
  attributes.principal: "urn:oid:0.9.2342.19200300.100.1.1"
  attributes.groups: "urn:oid:1.3.6.1.4.1.5923.1.5.1."
xpack.security.authc.realms.saml.saml_eng:
  order: 4
  idp.metadata.path: saml/idp-external.xml
  idp.entity_id: "https://engineering.sso.example.net/"
  sp.entity_id:  "https://kibana.engineering.example.com/"
  sp.acs: "https://kibana.engineering.example.com/api/security/saml/callback"
  sp.logout: "https://kibana.engineering.example.com/logout"
  attributes.principal: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"

It is possible to have one or more Kibana instances that use SAML, while other instances use basic authentication against another realm type (e.g. Native or LDAP).

You must create a SAML realm and configure it accordingly in Elasticsearch. See Configure Elasticsearch for SAML authentication

The realm is designed with the assumption that there needs to be a privileged entity acting as an authentication proxy. In this case, the custom web application is the authentication proxy handling the authentication of end users (more correctly, "delegating" the authentication to the SAML Identity Provider). The SAML related APIs require authentication and the necessary authorization level for the authenticated user. For this reason, you must create a Service Account user and assign it a role that gives it the manage_saml cluster privilege. The use of the manage_token cluster privilege will be necessary after the authentication takes place, so that the service account user can maintain access in order refresh access tokens on behalf of the authenticated users or to subsequently log them out.

resp = client.security.put_role(
    name="saml-service-role",
    cluster=[
        "manage_saml",
        "manage_token"
    ],
)
print(resp)

const response = await client.security.putRole({
  name: "saml-service-role",
  cluster: ["manage_saml", "manage_token"],
});
console.log(response);

POST /_security/role/saml-service-role
{
  "cluster" : ["manage_saml", "manage_token"]
}

resp = client.security.put_user(
    username="saml-service-user",
    password="<somePasswordHere>",
    roles=[
        "saml-service-role"
    ],
)
print(resp)

const response = await client.security.putUser({
  username: "saml-service-user",
  password: "<somePasswordHere>",
  roles: ["saml-service-role"],
});
console.log(response);

POST /_security/user/saml-service-user
{
  "password" : "<somePasswordHere>",
  "roles"    : ["saml-service-role"]
}

On a high level, the custom web application would need to perform the following steps in order to authenticate a user with SAML against Elasticsearch:

Elasticsearch can also handle the IdP-initiated Single Sign On flow of the SAML 2 Web Browser SSO profile. In this case the authentication starts with an unsolicited authentication response from the SAML Identity Provider. The difference with the SP initiated SSO is that the web application needs to handle requests to the sp.acs that will not come as responses to previous redirections. As such, it will not have a session for the user already, and it will not have any stored values for the id parameter. The request to the _security/saml/authenticate API will look like the one below in this case:

resp = client.security.saml_authenticate(
    content="PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
    ids=[],
)
print(resp)

const response = await client.security.samlAuthenticate({
  content:
    "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
  ids: [],
});
console.log(response);

POST /_security/saml/authenticate
{
  "content" : "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6cHJvdG9jb2wiIHhtbG5zOnNhbWw9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMD.....",
  "ids" : []
}

For SP-initiated Single Logout, the IdP may send back a logout response which can be verified by Elasticsearch using the SAML complete logout API.