In general, Elasticsearch expects that the configured value for an attribute will be a URI such as urn:oid:0.9.2342.19200300.100.1.1, however there are some additional names that can be used:

The example below configures a realm to use a persistent nameid for the principal, and the attribute with the friendlyName "roles" for the user’s groups.

xpack.security.authc.realms.saml1:
  type: saml
  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/v1/saml"
  attributes.principal: "nameid:persistent"
  attributes.groups: "roles"

The Elasticsearch SAML realm can be configured to map SAML attributes to the following properties on the authenticated user:

There are some occasions where the IdP’s attribute may contain more information than you wish to use within Elasticsearch. A common example of this is one where the IdP works exclusively with email addresses, but you would like the user’s principal to use the local-name part of the email address. For example if their email address was james.wong@staff.example.com, then you would like their principal to simply be james.wong.

This can be achieved using the attribute_patterns setting in the Elasticsearch realm, as demonstrated in the realm configuration below:

xpack.security.authc.realms.saml1:
  type: saml
  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/v1/saml"
  attributes.principal: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  attribute_patterns.principal: "^([^@]+)@staff\\.example\\.com$"

In this case, the user’s principal is mapped from an email attribute, but a regular expression is applied to the value before it is assigned to the user. If the regular expression matches, then the result of the first group is used as effective value. If the regular expression does not match then the attribute mapping fails.

In this example, the email address must belong to the staff.example.com domain, and then the local-part (anything before the @) is used as the principal. Any users who try to login using a different email domain will fail because the regular expression will not match against their email address, and thus their principal attribute - which is mandatory - will not be populated.

Small mistakes in these regular expressions can have significant security consequences. For example, if we accidentally left off the trailing $ from the example above, then we would match any email address where the domain starts with staff.example.com, and this would accept an email address such as admin@staff.example.com.attacker.net. It is important that you make sure your regular expressions are as precise as possible so that you do not inadvertently open an avenue for user impersonation attacks.

One of the values that Elasticsearch reads from the IdP’s SAML metadata is the <SingleLogoutService>. In order for Single Logout to work with the Elastic stack, Elasticsearch requires that this exist and support a binding of urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect.

The Elastic Stack will send both <LogoutRequest> and <LogoutResponse> messages to this service as appropriate.

The Elasticsearch realm setting sp.logout specifies a URL in Kibana to which the IdP can send both <LogoutRequest> and <LogoutResponse> messages. This service uses the SAML HTTP-Redirect binding.

Elasticsearch will process <LogoutRequest> messages, and perform a global signout that invalidates any existing Elasticsearch security tokens that are associated with the provided SAML session.

If you do not configure a value for sp.logout, Elasticsearch will refuse all <LogoutRequest> messages.

It is common for IdPs to require that LogoutRequest messages be signed, so you may need to configure signing credentials.

If your IdP provides a <SingleLogoutService> but you do not wish to use it, you can configure idp.use_single_logout: false in your SAML realm, and Elasticsearch will ignore the SLO service that your IdP provides. In this case, when a user logs out of Kibana it will invalidate their Elasticsearch session (security token), but will not perform any logout at the IdP.

If your IdP does not support Single Logout, or you choose not to use it, then Kibana will perform a "local logout" only.

This means that Kibana will invalidate the session token it is using to communicate with Elasticsearch, but will not be able to perform any sort of invalidation of the Identity Provider session. In most cases this will mean that Kibana users are still considered to be logged in to the IdP. Consequently, if the user navigates to the Kibana landing page, they will be automatically reauthenticated, and will commence a new Kibana session without needing to enter any credentials.

The possible solutions to this problem are:

Elasticsearch supports certificates and keys in either PEM, PKCS#12 or JKS format. Some Identity Providers are more restrictive in the formats they support, and will require you to provide the certificates as a file in a particular format. You should consult the documentation for your IdP to determine what formats they support. Since PEM format is the most commonly supported format, the examples below will generate certificates in that format.

Using the elasticsearch-certutil tool, you can generate a signing certificate with the following command:

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

This will

The generated zip archive will contain 3 files:

Encryption certificates can be generated with the same process.

By default, X-Pack security will sign all outgoing SAML messages if a signing key has been configured.

If you wish to use PEM formatted keys and certificates for signing, then you should configure the following settings on the SAML realm:

If you wish to use PKCS#12 formatted files or a Java Keystore for signing, then you should configure the following settings on the SAML realm:

If you wish to sign some, but not all outgoing SAML messages, then you should configure the following setting on the SAML realm:

X-Pack security supports a single key for message decryption. If a key is configured, then X-Pack security will attempt to use it to decrypt EncryptedAssertion and EncryptedAttribute elements in Authentication responses, and EncryptedID elements in Logout requests.

X-Pack security will reject any SAML message that contains an EncryptedAssertion that cannot be decrypted.

If an Assertion contains both encrypted and plain-text attributes, then failure to decrypt the encrypted attributes will not cause an automatic rejection. Rather, X-Pack security will process the available plain-text attributes (and any EncryptedAttributes that could be decrypted).

If you wish to use PEM formatted keys and certificates for SAML encryption, then you should configure the following settings on the SAML realm:

If you wish to use PKCS#12 formatted files or a Java Keystore for SAML encryption, then you should configure the following settings on the SAML realm: