SAML authentication

The Elastic Stack supports SAML single sign-on (SSO) into Kibana, using Elasticsearch as a backend service. This guide helps you configure SAML SSO so that users can log in to Kibana using your organization's identity provider (IdP).

For a detailed walk-through of how to implement SAML authentication for Kibana with Microsoft Entra ID as an identity provider, refer to Set up SAML with Microsoft Entra ID.

Because this feature is designed with Kibana in mind, most sections of this guide assume Kibana is used. To learn how a custom web application could use the SAML REST APIs to authenticate users to Elasticsearch without Kibana, refer to SAML without Kibana.

Note

Elastic Stack SSO is a subscription feature.

Tip

This page describes implementing SAML SSO at the deployment or cluster level, for the purposes of authenticating with a Kibana instance.

Depending on your deployment type, you can also configure SSO for the following use cases:

In SAML terminology, your identity system is the Identity Provider (IdP): it authenticates users and issues SAML assertions about them. The Elastic Stack acts as a Service Provider (SP): Kibana initiates and coordinates the SSO flow, and Elasticsearch validates the SAML assertions and issues session tokens.

To enable SSO, register the Elastic Stack as a known SP within your IdP, and configure Elasticsearch and Kibana to trust and communicate with your IdP. When SAML is enabled in Kibana, unauthenticated users are redirected to the IdP login page by default.

The Elastic Stack implements SAML SSO with the SAML 2.0 Web Browser SSO profile. Because the flow is browser-based, the SAML realm is not suitable for standard REST clients. If you configure SAML for Kibana, also add a realm for API access, such as the native realm.

SAML also supports Single Logout, which ends both the Kibana session and the IdP session when a user logs out.

Setting up SAML requires coordination with your Identity Provider (IdP). You'll collect some information from it, and register the Elastic Stack as a Service Provider (SP) within it.

The Elastic Stack supports the SAML 2.0 Web Browser SSO and Single Logout profiles, and can integrate with any IdP that supports at least the Web Browser SSO profile. It has been tested with Microsoft Active Directory Federation Services (ADFS), Microsoft Entra ID, and Okta.

To configure Elasticsearch, you will need a standard XML-formatted SAML metadata document from your IdP, which defines its capabilities and features. You should be able to download or generate it from your IdP's administration interface. You can pass it to Elasticsearch as a URL (preferred, so Elasticsearch reloads it automatically when it changes) or as a local file. For more information, refer to Create a SAML realm in Elasticsearch.

Most IdPs will provide an appropriate metadata file with all the features that the Elastic Stack requires. Verify that your IdP's metadata includes the following:

  • An <EntityDescriptor> with an entityID that you will configure as idp.entity_id in the Elasticsearch realm
  • An <IDPSSODescriptor> that supports the SAML 2.0 protocol (urn:oasis:names:tc:SAML:2.0:protocol)
  • At least one <KeyDescriptor> configured for signing (with use="signing", or use left unspecified)
  • A <SingleSignOnService> with binding of HTTP-Redirect (urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect)
  • If you want Single Logout: a <SingleLogoutService> with binding of HTTP-Redirect (urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect)

All messages from the IdP must be signed. For <Response> messages, the signature can be on the response itself or on individual assertions. For <LogoutRequest> messages, the signature must be provided as a URL parameter, as required by the HTTP-Redirect binding.

If you're using a self-managed cluster:

Note

Elastic Cloud Hosted, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes enable HTTPS and the token service by default.

Follow these steps to configure SAML SSO for the Elastic Stack.

  1. Configure your identity provider

    Tip

    If your IdP supports SP metadata import, you can generate an SP metadata file after configuring the Elasticsearch realm and import it into your IdP to register the Elastic Stack as a Service Provider automatically. Refer to Generate SP metadata.

    Register the Elastic Stack as a SAML service provider in your IdP. The exact steps vary by provider, but you generally need to do the following:

    1. Create a new SAML application or service provider entry in your IdP.
    2. Set the Assertion Consumer Service (ACS) URL to your Kibana base URL followed by /api/security/saml/callback (for example, https://kibana.example.com/api/security/saml/callback).
    3. Set the entity ID to a URI that uniquely identifies this Kibana instance as a Service Provider. We recommend using the Kibana base URL (for example, https://kibana.example.com).
    4. Set the logout URL to your Kibana base URL followed by /logout if your IdP supports Single Logout (for example, https://kibana.example.com/logout).
    5. Identify the user attributes your IdP can include in SAML assertions. Consult your IdP documentation or local admin. This varies between providers. These attribute URIs will be used to configure the attribute mapping in the Elasticsearch realm.
    6. Note the IdP metadata URL or download the metadata file. You will need this for the Elasticsearch configuration.
    7. Optional: If your IdP requires signed outgoing SAML messages (authentication requests or logout requests), provide your Elasticsearch signing certificate to the IdP at this stage. Refer to Signing and encryption for how to generate certificates and configure signing in Elasticsearch.

  2. Create a SAML realm in Elasticsearch

    Add a SAML realm to your Elasticsearch configuration and restart the cluster for the changes to take effect.

    The realm ties together three pieces: your IdP's identity and metadata, the Elastic Stack's service provider endpoints, and the attribute mapping that tells Elasticsearch how to identify users from the IdP's assertions.

    xpack.security.authc.realms.saml.saml1:
  order: 2
  idp.metadata.path: "https://idp.example.com/metadata"
  idp.entity_id: "https://idp.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."
    1. Controls realm priority. A lower number means higher priority. Assign SSO realms higher order values than password-based realms (native, LDAP). If you're using Elastic Cloud on Kubernetes, set order to a value greater than the file realm (default -100) and native realm (default -99).

    The following describes the most commonly used settings for a SAML realm. For the full list of available settings, refer to SAML realm settings.

    idp.metadata.path

    The path or URL to the SAML metadata file for your Identity Provider. A URL is recommended so Elasticsearch reloads it automatically when it changes.

    Tip

    When configuring a file path in an Elasticsearch setting, keep in mind:

    • In self-managed clusters, file path settings are resolved relative to the Elasticsearch config directory. Elasticsearch monitors this file for changes and reloads the configuration whenever it is updated.
    • If you're using Elastic Cloud Hosted or Elastic Cloud Enterprise, upload the file before referencing it in the configuration. For Elastic Cloud Hosted, upload it as a custom bundle. For Elastic Cloud Enterprise, follow the equivalent ECE procedure.
    • If you're using Elastic Cloud on Kubernetes, install the file as a custom configuration file.
    idp.entity_id
    The identifier (SAML EntityID) that your IdP uses. Must match the entityID attribute in the IdP metadata exactly. The comparison is case-sensitive.
    sp.entity_id
    A unique identifier for your Kibana instance, expressed as a URI. Must match exactly the entity ID you configure in your IdP. The comparison is case-sensitive. We recommend using the Kibana base URL.
    sp.acs
    The URL of the Assertion Consumer Service within Kibana that receives authentication responses from your IdP, using the HTTP-POST binding. For example, https://kibana.example.com/api/security/saml/callback. This URL must be reachable from users' browsers, but does not need to be directly accessible by Elasticsearch or the IdP. If Kibana is behind a reverse proxy, use the public-facing URL.
    sp.logout
    The URL of the Single Logout service within Kibana that receives logout messages from your IdP. For example, https://kibana.example.com/logout. Required for SAML Single Logout. If not configured, Elasticsearch refuses all <LogoutRequest> messages from the IdP.
    attributes.principal (required)
    The SAML attribute that Elasticsearch uses as the username (principal). Replace with the URI your IdP uses. Attribute URIs vary between providers. If your IdP uses NameID, use nameid here. See Attribute mapping.
    attributes.groups (recommended)
    The SAML attribute that maps to group memberships. Replace with the URI your IdP uses. Recommended if you want to assign roles based on IdP group memberships. See Attribute mapping.
    Note

    If your IdP requires signed requests or uses encrypted assertions, refer to Signing and encryption.

    Note

    If your IdP supports Authentication Context restrictions (for example, to require MFA), you can configure req_authn_context_class_ref in the realm. Refer to Request specific authentication methods.

    When a user authenticates through SAML, the IdP sends an assertion containing attributes (pieces of information about the user such as their username, email address, or group memberships). The attributes.* realm settings tell Elasticsearch which SAML attribute URI to use for each Elasticsearch user property.

    Warning

    The attribute URIs must exactly match what your IdP sends in the assertion. A mismatch silently breaks authentication: the login might appear to succeed but the user's principal or group memberships will be missing or incorrect. Verify the exact URIs with your IdP administrator or by inspecting a captured SAML assertion.

    The most important mappings are attributes.principal and attributes.groups: attributes.principal is required and determines the username Elasticsearch assigns to the authenticated user, and attributes.groups is recommended if you want to assign roles based on IdP group memberships.

    For a complete reference of mappable user properties, special attribute names, and advanced patterns, refer to Map SAML attributes to Elasticsearch user properties.

  3. Configure Kibana for SAML authentication

    Add the SAML authentication provider to your Kibana configuration and restart Kibana for the changes to take effect.

    xpack.security.authc.providers:
  saml.saml1:
    order: 0
    realm: "saml1"
    1. Must match the SAML realm name defined in your Elasticsearch configuration.

    With this configuration, Kibana redirects all unauthenticated users to your IdP for login.

    Note

    If you run multiple Kibana instances connected to the same cluster or deployment (for example, behind a load balancer), apply this SAML provider configuration to every instance. If each instance is accessed through a different URL, each needs its own SAML realm. Refer to Multiple Kibana instances and URLs.

    To let some users, such as local administrators, log in with a username and password, enable a basic provider alongside SAML:

    xpack.security.authc.providers:
  saml.saml1:
    order: 0
    realm: "saml1"
    description: "Log in with SSO"
  basic.basic1:
    order: 1

    When multiple authentication providers are configured, users view a login selector and can select their preferred method. Users who log in with basic authentication must have credentials in a configured Elasticsearch realm such as native or LDAP. For more details, refer to Authentication in Kibana > Multiple authentication providers.

  4. Configure role mappings

    SAML authentication identifies users to the Elastic Stack, but does not automatically grant them any access. You must map SAML users to Elasticsearch roles before they can do anything.

    Role mappings connect SAML user identities to Elasticsearch roles, but the roles themselves must exist first. You can use built-in roles such as superuser or kibana_admin for initial testing. For production, create custom roles with appropriate access to your data and Kibana privileges.

    You can create role mappings in the Role Mappings page in Kibana or with the role mapping API. For the general concepts, UI workflow, and rule syntax, refer to Map external users and groups to roles. The following examples show common SAML patterns.

    Note

    Role mapping files cannot be used for SAML users.

    This is an example of a basic role mapping that grants the example_role role to any user who authenticates against the saml1 realm:

    				PUT /_security/role_mapping/saml-all-users
					{
  "roles": [ "example_role" ],
  "enabled": true,
  "rules": {
    "field": { "realm.name": "saml1" }
  }
}
    1. Replace example_role with the role you want to assign.

    The user fields available in role mapping rules are derived from the SAML attributes configured in the realm:

    • username: The principal attribute
    • dn: The dn attribute
    • groups: The groups attribute
    • metadata: See User metadata

    If your IdP provides group memberships, configure attributes.groups in the Elasticsearch realm and then use it in a role mapping rule.

    This example grants the finance_data role to users in the finance-team group authenticating through saml1 realm:

    				PUT /_security/role_mapping/saml-finance
					{
  "roles": [ "finance_data" ],
  "enabled": true,
  "rules": { "all": [
    { "field": { "realm.name": "saml1" } },
    { "field": { "groups": "finance-team" } }
  ] }
}
    1. The groups field supports wildcards (*). Refer to the role mapping API for the full rule syntax.

    If your users also exist in a repository that can be directly accessed by Elasticsearch (such as an LDAP directory), you can use authorization realms instead of role mappings:

    1. Configure attributes.principal in your SAML realm to identify the user for the lookup.
    2. Create a realm that can look up users from your repository (for example, an ldap realm).
    3. Set authorization_realms in your SAML realm to the name of the realm from step 2.

  5. Test SAML authentication

    After applying all changes, open Kibana in a browser. You should be redirected to your IdP's login page. After authenticating, you should be returned to Kibana as a logged-in user.

    To verify the user's identity and roles, use the authenticate API:

    				GET /_security/_authenticate

    The response shows the authenticated username, assigned roles, and SAML metadata. If roles are missing or incorrect, review your role mapping rules, the realm configuration, and the SAML attributes your IdP is sending.

    Tip

    If SAML is not yet working and you cannot access Kibana, make sure you have configured a basic authentication provider as described in Allow both SAML and basic authentication.

    If something does not work as expected, refer to the SAML troubleshooting documentation for common issues and their resolutions, including how to enable debug logging to diagnose authentication failures.

The following sections cover optional features and specific SAML behaviors that go beyond the standard configuration steps. They address particular aspects of the protocol, such as logout coordination, message signing, or authentication constraints, that you might need depending on your IdP's capabilities and your organization's security requirements.

Depending on your IdP, you might need to sign outgoing SAML messages (authentication or logout requests), decrypt encrypted assertions, or both. Elasticsearch supports both cases using X.509 certificates configured in the SAML realm.

For a complete example including certificate generation and configuration for PEM, PKCS#12, and JKS formats, refer to Configure SAML signing and encryption.

For available settings, refer to SAML realm signing settings and SAML realm encryption settings.

The SAML protocol supports Single Logout (SLO), which ends both the Kibana session and the IdP session when a user logs out. Support for SLO varies between identity providers. Consult your IdP's documentation to determine what logout services it offers.

By default, Elasticsearch uses SAML SLO when all the following are true:

  • Your IdP metadata includes a <SingleLogoutService> with HTTP-Redirect binding
  • Your IdP releases a NameID in the SAML assertion
  • You have configured sp.logout
  • The setting idp.use_single_logout is not false

The sp.logout setting specifies a URL in Kibana to which the IdP can send both <LogoutRequest> and <LogoutResponse> messages using the HTTP-Redirect binding. Elasticsearch sends both message types to the IdP's <SingleLogoutService> as appropriate. When Elasticsearch receives a <LogoutRequest>, it performs a global signout that invalidates all Elasticsearch security tokens associated with that SAML session.

If you don't configure sp.logout, Elasticsearch will refuse all <LogoutRequest> messages from the IdP.

When SLO is not available

If your IdP does not support Single Logout, or you choose not to use it, Kibana performs a local logout only: the Elasticsearch session token is invalidated, but the IdP session remains active. Users are still considered logged in to the IdP and will be automatically reauthenticated if they navigate back to the Kibana landing page without entering credentials.

The possible solutions to this problem are:

  • Ask your IdP administrator or vendor to provide a Single Logout service.
  • If your IdP does provide a Single Logout service, make sure it is included in the IdP metadata file and do not set idp.use_single_logout to false.
  • Advise your users to close their browser after logging out of Kibana.
  • Enable force_authn: true in your SAML realm. This forces fresh authentication at the IdP on every login, preventing session reuse even without SLO. It defaults to false because it adds friction to the user experience, but it is an effective protection against users piggybacking on existing IdP sessions.

To disable SLO even when your IdP advertises support for it, set idp.use_single_logout: false in the realm configuration.

Note

Some IdPs require logout requests to be signed. Check your IdP's documentation and configure signing certificates if needed.

It is sometimes necessary for a SAML SP to impose specific restrictions on the authentication that takes place at the IdP. The restrictions might relate to the authentication method used — such as password, client certificates, or MFA — the user identification method during registration, and other details. Elasticsearch implements SAML 2.0 Authentication Context for this purpose.

The SAML SP sends a set of Authentication Context Class Reference values in the Authentication Request, describing the restrictions to impose on the IdP. The IdP attempts to satisfy those restrictions and indicates the result in its Authentication Response. If the IdP cannot grant the requested restrictions, authentication fails.

Configure the class reference values using req_authn_context_class_ref in your SAML realm. For example:

xpack.security.authc.realms.saml.saml1:
  req_authn_context_class_ref:
    - "http://schemas.microsoft.com/claims/multipleauthn"
  1. This example uses the Entra ID URI for MFA. The exact URI values depend on your IdP. Some standard SAML 2.0 values such as urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport are widely supported, but IdP-specific URIs are common. Consult your IdP's documentation.

Elasticsearch supports only the exact comparison method. The Authentication Response must include one of the specified values; otherwise, authentication fails. For more details, refer to req_authn_context_class_ref in SAML realm settings.

The SP metadata file is an XML document that describes your Elastic Stack as a SAML Service Provider. It contains your entity ID, ACS URL, logout URL, and any signing or encryption certificates configured in the realm. Some Identity Providers can import this file to configure the integration automatically, instead of requiring you to enter each value individually when registering the Elastic Stack in your IdP.

Once you have configured a SAML realm in Elasticsearch, you can generate its SP metadata file using the SAML service provider metadata API or the bin/elasticsearch-saml-metadata command.

You can generate the SAML metadata by issuing the API request to Elasticsearch and store it as an XML file using tools like jq. For example, the following command generates the metadata for the SAML realm saml1 and saves it to a metadata.xml file:

				
					curl -u user_name:password -X GET https://elasticsearch.example.com:9200/_security/saml/metadata/saml1 -H 'Content-Type: application/json' | jq -r '.[]' > metadata.xml  #
  1. Replace elasticsearch.example.com:9200 with your actual Elasticsearch endpoint.

You can generate the SAML metadata by running the bin/elasticsearch-saml-metadata command.

bin/elasticsearch-saml-metadata --realm saml1

To generate the Service Provider metadata using the elasticsearch-saml-metadata command in Elastic Cloud on Kubernetes, you need to run the command using kubectl, and then copy the generated metadata file to your local machine. For example:

# Create metadata
kubectl exec -it elasticsearch-sample-es-default-0 -- sh -c "/usr/share/elasticsearch/bin/elasticsearch-saml-metadata --realm saml1"

# Copy metadata file
kubectl cp elasticsearch-sample-es-default-0:/usr/share/elasticsearch/saml-elasticsearch-metadata.xml saml-elasticsearch-metadata.xml

Multiple Kibana instances and URLs

Use this configuration when each Kibana instance is reached through a different URL. If multiple instances serve the same URL (for example, behind a load balancer), use a single SAML realm and apply the same provider settings to every instance, as shown in Configure Kibana for SAML authentication.

When instances use different URLs and authenticate against the same Elasticsearch cluster, each instance requires its own SAML realm. Each realm must have its own unique Entity ID (sp.entity_id) and Assertion Consumer Service URL (sp.acs), but they can all use the same Identity Provider. In Kibana, configure each instance's SAML provider to point to its corresponding realm.

The following is an example of settings for a cluster with three different Kibana instances, two 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: "<sso-example-url>"
  sp.entity_id: "<kibana-finance-example-url>"
  sp.acs: "<kibana-finance-example-url>/api/security/saml/callback"
  sp.logout: "<kibana-finance-example-url>/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: "<sso-example-url>"
  sp.entity_id: "<kibana-sales-example-url>"
  sp.acs: "<kibana-sales-example-url>/api/security/saml/callback"
  sp.logout: "<kibana-sales-example-url>/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: "<engineering-sso-example-url>"
  sp.entity_id: "<kibana-engineering-example-url>"
  sp.acs: "<kibana-engineering-example-url>/api/security/saml/callback"
  sp.logout: "<kibana-engineering-example-url>/logout"
  attributes.principal: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"
Note

You can also mix authentication methods across instances: some Kibana instances can use SAML while others use basic authentication against another realm type (for example, Native or LDAP).

If you're building a custom web application that needs to authenticate users against Elasticsearch using SAML (without Kibana), you can use the SAML REST APIs to implement the full authentication flow directly. This is relevant when you have a custom portal, a microservice-based architecture, or any scenario where the browser-based SSO flow must be handled by your own application code rather than by Kibana.

The application acts as an authentication proxy: it drives the SP-initiated or IdP-initiated SSO flow, exchanges the SAML response for an Elasticsearch access token and refresh token, and uses that token as a Bearer credential for subsequent requests.

For the complete implementation guide, including service account setup, SP-initiated and IdP-initiated flows, and logout handling, refer to SAML without Kibana.

Edit page