SAML single sign-on in Elasticsearch requires coordination between the Elasticsearch SAML realm, Kibana, and your Identity Provider. Misalignment in any component produces errors that can be difficult to trace. This article covers the most frequent SAML configuration errors and how to resolve them.
SAML Realm Configuration in elasticsearch.yml
The SAML realm is defined under xpack.security.authc.realms.saml in elasticsearch.yml. A minimal configuration looks like this:
xpack.security.authc.realms.saml.saml1:
order: 2
idp.metadata.path: "saml/idp-metadata.xml"
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: "nameid"
attributes.groups: "groups"
The sp.entity_id value must exactly match the Service Provider Entity ID registered in your IdP. A mismatch here produces an error on the IdP side, often resulting in a generic "authentication failed" message in Elasticsearch logs. The sp.acs (Assertion Consumer Service) URL must point to Kibana's SAML callback endpoint and must match the ACS URL configured in the IdP application.
The idp.metadata.path accepts either a local file path (resolved relative to the Elasticsearch config directory) or an HTTPS URL. When using a URL, Elasticsearch fetches the metadata at startup and periodically refreshes it. If the metadata endpoint is unreachable or returns invalid XML, the realm fails to initialize. Check the Elasticsearch log for SamlRealm errors during node startup if authentication never works at all.
Entity ID and Redirect URI Mismatches
The idp.entity_id must match the EntityID declared in the IdP's own metadata. Elasticsearch validates incoming SAML responses against this value, and a mismatch causes the response to be rejected with a message like "SAML response is not valid - Issuer does not match." Copy the entity ID directly from your IdP metadata XML rather than typing it manually.
Redirect URI mismatches are another frequent issue. The sp.acs URL in elasticsearch.yml must match the Reply URL (or ACS URL) configured in the IdP. In Azure Entra ID, this is set under Enterprise Applications > your app > Single sign-on > Basic SAML Configuration. In Okta, it's the "Single sign on URL" field. Trailing slashes, protocol differences (http vs https), and port numbers all matter - the strings must be identical.
Each SAML realm in Elasticsearch requires a unique sp.entity_id and a unique sp.acs. If you configure multiple SAML realms (for example, one for Okta and one for ADFS), each must have distinct values for both settings.
Certificate and Signing Errors
SAML responses and assertions are typically signed by the IdP. Elasticsearch validates these signatures using the certificate published in the IdP metadata. If the IdP rotates its signing certificate but the locally cached metadata file still contains the old certificate, signature validation fails. The error log will show messages referencing signature verification failure or invalid signature.
To fix this, re-download the IdP metadata file and place it in the configured path. If you use an HTTPS metadata URL, restart the Elasticsearch node to force a metadata refresh. You can also set idp.metadata.path to the HTTPS endpoint URL so that Elasticsearch fetches updated metadata automatically.
When configuring Elasticsearch to sign authentication requests, configure signing.certificate and signing.key in the SAML realm settings. Self-signed certificates work, but the IdP must trust the SP's signing certificate. Missing or expired SP signing certificates cause the IdP to reject the authentication request.
Attribute Mapping and Clock Skew
Elasticsearch maps SAML response attributes to user properties through the attributes.* settings. The attributes.principal setting is required - it specifies which SAML attribute becomes the Elasticsearch username. Common values include nameid (to use the NameID element), http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, or a custom attribute name like uid.
If the IdP sends attributes under different names than what Elasticsearch expects, authentication fails with "Cannot find any matching attributes" in the log. The attribute names are case-sensitive. Use TRACE logging (described below) to see exactly which attributes the IdP is sending, then adjust the attributes.principal and attributes.groups values to match.
attributes.principal: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
attributes.groups: "http://schemas.xmlsoap.org/claims/Group"
attributes.mail: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
Clock skew between the IdP and Elasticsearch nodes causes assertion validation failures. SAML assertions include NotBefore and NotOnOrAfter timestamps. If the Elasticsearch node's clock is outside that window, the assertion is rejected. The allowed_clock_skew setting (default 3m) controls how much drift is tolerated. If you see errors about assertions being expired or not yet valid, first sync clocks via NTP, then increase allowed_clock_skew as a temporary workaround.
Kibana SAML Setup and Debugging
Kibana must be configured to use the SAML provider. In kibana.yml:
xpack.security.authc.providers:
saml.saml1:
order: 0
realm: "saml1"
description: "Log in with SSO"
basic.basic1:
order: 1
The realm value under saml.saml1 must match the realm name in elasticsearch.yml (the saml1 in xpack.security.authc.realms.saml.saml1). A mismatch here means Kibana sends authentication requests to a non-existent realm, producing "realm not found" errors. Keep a basic provider as a fallback so you can still log in with local credentials if SAML breaks.
For debugging, enable TRACE logging on the SAML authentication package by calling the cluster settings API:
PUT /_cluster/settings
{
"transient": {
"logger.org.elasticsearch.xpack.security.authc.saml": "TRACE"
}
}
This logs the full SAML response content, attribute values received from the IdP, signature validation steps, and assertion parsing details. It is the single most effective tool for diagnosing SAML issues. Disable it after debugging since it logs sensitive authentication data.
IdP-specific pitfalls to watch for: Okta requires the "Group Attribute Statements" to be explicitly configured in the SAML app settings or no group attributes are sent. Azure Entra ID uses claim URIs as attribute names (not short names like "groups"), and you must add a group claim in the Token Configuration section. ADFS requires a Relying Party Trust with claim rules that map AD attributes to outgoing SAML attributes - missing claim rules result in empty attribute statements.
