WARNING: Version 6.2 of the Elastic Stack has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
SAML Authentication
editSAML Authentication
editX-Pack security supports user authentication using SAML Single Sign On. X-Pack security provides this support using the Web Browser SSO profile of the SAML 2.0 protocol.
This protocol is specifically designed to support authentication via an interactive web browser, so it does not operate as a standard authentication realm. Instead, X-Pack security provides features in Kibana and Elasticsearch that work together to enable interactive SAML sessions.
This means that the SAML realm is not suitable for use by standard REST clients. If you configure a SAML realm for use in Kibana, you should also configure another realm, such as the native realm in your authentication chain.
In order to simplify the process of configuring SAML authentication within the Elastic Stack, there is a step-by-step guide to Configuring Elasticsearch and Kibana to use SAML Single-Sign-On.
The remainder of this document will describe Elasticsearch specific configuration options for SAML realms.
SAML Realm Settings
editSetting |
Required |
Description |
|
yes |
Indicates the realm type. Must be set to |
|
no |
Indicates the priority of this realm within the realm chain.
Realms with a lower order are consulted first. Although not
required, we recommend explicitly setting this value when
you configure multiple realms. Defaults to |
|
no |
Indicates whether this realm is enabled or disabled. Enables
you to disable a realm without removing its configuration.
Defaults to |
|
yes |
The Entity ID of the SAML Identity Provider |
|
yes |
The path (recommended) or URL to a SAML 2.0 metadata file
describing the capabilities and configuration of the Identity
Provider.
If a path is provided, then it is resolved relative to the
Elasticsearch config directory.
If a URL is provided, then it must be either a |
|
no |
Controls the frequency with which |
|
no |
Indicates whether to utilise the Identity Provider’s Single
Logout service (if one exists in the IdP metadata file).
Defaults to |
|
yes |
The Entity ID to use for this SAML Service Provider.
This should be entered as a URI. We recommend that you use the
base URL of your Kibana instance,
e.g. |
|
yes |
The URL of the Assertion Consumer Service within Kibana.
Typically this will be the "api/security/v1/saml" endpoint of
your Kibana server,
e.g. |
|
no |
The URL of the Single Logout service within Kibana.
Typically this will be the "logout" endpoint of
your Kibana server,
e.g. |
|
yes |
The Name of the SAML attribute that should be used as the X-Pack security user’s principal (username) |
|
no |
The Name of the SAML attribute that should be used to populate X-Pack security user’s groups |
|
no |
The Name of the SAML attribute that should be used to populate X-Pack security user’s full name |
|
no |
The Name of the SAML attribute that should be used to populate X-Pack security user’s email address |
|
no |
The Name of the SAML attribute that should be used to populate X-Pack security user’s X.500 Distinguished Name |
|
no |
A java regular expression that is matched against the SAML attribute
specified by |
|
no |
As per |
|
no |
As per |
|
no |
As per |
|
no |
As per |
|
no |
The NameID format that should be requested when asking the IdP
to authenticate the current user.
Defaults to requesting transient names
( |
|
no |
The value of the |
|
no |
The value of the |
|
no |
Whether to set the |
|
no |
Whether to populate the Elasticsearch user’s metadata with the values that
are provided by the SAML attributes. Defaults to |
|
no |
The maximum amount of skew that can be tolerated between the IdP’s clock and the Elasticsearch node’s clock. Defaults to 3 minutes. |
SAML Realm Signing Settings
editIf a signing key is configured (i.e. is one of signing.key
or signing.keystore.path
has been set), then
X-Pack security will sign outgoing SAML messages. Signing can be configured using the following settings.
Setting |
Required |
Description |
|
no |
A list of SAML message types that should be signed, or |
|
no |
Specifies the path to the PEM encoded private key to use for
SAML message signing.
|
|
no |
(Secure) Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted. |
|
no |
Specifies the path to the PEM encoded certificate (or certificate
chain) that corresponds to the |
|
no |
The path to the keystore that contains a private key and
certificate.
Must be either a Java Keystore (jks) or a PKCS#12 file.
|
|
no |
The type of the keystore. Must be one of "jks" or "PKCS12". Defaults to "PKCS12" if the keystore path ends in ".p12", ".pfx" or "pkcs12", otherwise uses "jks" |
|
no |
Specifies the alias of the key within the keystore that should be
used for SAML message signing. Defaults to |
|
no |
(Secure) The password to the keystore. |
|
no |
(Secure) The password for the key in the keystore. Defaults to the keystore password. |
SAML Realm Encryption Settings
editIf an encryption key is configured (i.e. is one of encryption.key
or
encryption.keystore.path
has been set), then X-Pack security will publish
an encryption certificate when generating metadata, and will attempt to
decrypt incoming SAML content.
Encryption can be configured using the following settings.
Setting |
Required |
Description |
|
no |
Specifies the path to the PEM encoded private key to use for
SAML message descryption.
|
|
no |
(Secure) Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted. |
|
no |
Specifies the path to the PEM encoded certificate (or certificate
chain) that is associated with the |
|
no |
The path to the keystore that contains a private key and
certificate.
Must be either a Java Keystore (jks) or a PKCS#12 file.
|
|
no |
The type of the keystore. Must be one of "jks" or "PKCS12". Defaults to "PKCS12" if the keystore path ends in ".p12", ".pfx" or "pkcs12", otherwise uses "jks" |
|
no |
Specifies the alias of the key within the keystore that should be
used for SAML message encryption. Defaults to |
|
no |
(Secure) The password to the keystore. |
|
no |
(Secure) The password for the key in the keystore. |
SAML Realm SSL Settings
editIf you are loading the IdP metadata over SSL/TLS (that is, idp.metadata.path
is a URL using the https
protocol)
Then the following settings may be used to configure SSL. If these are not specified, then the X-Pack
default SSL settings are used.
These settings are not used for any purpose other than loading metadata over https.
Setting |
Required |
Description |
|
no |
Specifies the path to the PEM encoded private key to use for http
client authentication.
|
|
no |
Specifies the passphrase to decrypt the PEM encoded private key if
it is encrypted. May not be used with |
|
no |
(Secure)
Specifies the passphrase to decrypt the PEM encoded private key if
it is encrypted. May not be used with |
|
no |
Specifies the path to the PEM encoded certificate (or certificate
chain) that goes with the key. May only be used if |
|
no |
Specifies the paths to the PEM encoded certificate authority
certificates that should be trusted.
|
|
no |
The path to the keystore that contains a private key and
certificate.
Must be either a Java Keystore (jks) or a PKCS#12 file.
|
|
no |
The type of the keystore. Must be one of "jks" or "PKCS12". Defaults to "PKCS12" if the keystore path ends in ".p12", ".pfx" or "pkcs12", otherwise uses "jks" |
|
no |
The password to the keystore.
May not be used with |
|
no |
(Secure) The password to the keystore.
May not be used with |
|
no |
The password for the key in the keystore.
Defaults to the keystore password.
May not be used with |
|
no |
(Secure)
The password for the key in the keystore.
Defaults to the keystore password.
May not be used with |
|
no |
The path to the keystore that contains the certificates to trust.
Must be either a Java Keystore (jks) or a PKCS#12 file.
|
|
no |
The type of the truststore. Must be one of "jks" or "PKCS12". Defaults to "PKCS12" if the keystore path ends in ".p12", ".pfx" or "pkcs12", otherwise uses "jks" |
|
no |
The password to the truststore.
May not be used with |
|
no |
(Secure) The password to the truststore.
May not be used with |
|
no |
One of |
|
no |
Specifies the supported protocols for TLS/SSL. |
|
no |
Specifies the cipher suites that should be supported. |