SAML Authentication

X-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

Setting

Required

Description

type

yes

Indicates the realm type. Must be set to saml.

order

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 Integer.MAX_VALUE.

enabled

no

Indicates whether this realm is enabled or disabled. Enables you to disable a realm without removing its configuration. Defaults to true.

idp.entity_id

yes

The Entity ID of the SAML Identity Provider

idp.metadata.path

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 file URL or a https URL. X-Pack security will automatically poll this metadata resource and will reload the IdP configuration when changes are detected. File based resources are polled at a frequency determined by the global Elasticsearch resource.reload.interval.high setting, which defaults to 5 seconds. HTTPS resources are polled at a frequency determined by the realm’s idp.metadata.http.refresh setting.

idp.metadata.http.refresh

no

Controls the frequency with which https metadata is checked for changes. Defaults to 1 hour.

idp.use_single_logout

no

Indicates whether to utilise the Identity Provider’s Single Logout service (if one exists in the IdP metadata file). Defaults to true.

sp.entity_id

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. https://kibana.example.com/

sp.acs

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. https://kibana.example.com/api/security/v1/saml

sp.logout

no

The URL of the Single Logout service within Kibana. Typically this will be the "logout" endpoint of your Kibana server, e.g. https://kibana.example.com/logout

attributes.principal

yes

The Name of the SAML attribute that should be used as the X-Pack security user’s principal (username)

attributes.groups

no

The Name of the SAML attribute that should be used to populate X-Pack security user’s groups

attributes.name

no

The Name of the SAML attribute that should be used to populate X-Pack security user’s full name

attributes.mail

no

The Name of the SAML attribute that should be used to populate X-Pack security user’s email address

attributes.dn

no

The Name of the SAML attribute that should be used to populate X-Pack security user’s X.500 Distinguished Name

attribute_patterns.principal

no

A java regular expression that is matched against the SAML attribute specified by attributes.pattern before it is applied to the user’s principal property. The attribute value must match the pattern, and the value of the first capturing group is used as the principal. e.g. ^([^@]+)@example.com$ matches email addresses from the "example.com" domain and uses the local-part as the principal.

attribute_patterns.groups

no

As per attribute_patterns.principal, but for the group property.

attribute_patterns.name

no

As per attribute_patterns.principal, but for the name property.

attribute_patterns.mail

no

As per attribute_patterns.principal, but for the mail property.

attribute_patterns.dn

no

As per attribute_patterns.principal, but for the dn property.

nameid_format

no

The NameID format that should be requested when asking the IdP to authenticate the current user. Defaults to requesting transient names (urn:oasis:names:tc:SAML:2.0:nameid-format:transient)

nameid.allow_create

no

The value of the AllowCreate attribute of the NameIdPolicy element in an authentication request. Defaults to false

nameid.sp_qualifier

no

The value of the SPNameQualifier attribute of the NameIdPolicy element in an authentication request. The default is to not include the SPNameQualifier attribute.

force_authn

no

Whether to set the ForceAuthn attribute when requesting that the IdP authenticate the current user. If this is set to true, the IdP will be required to freshly establish the user’s identity, irrespective of any exiting sessions they may have. Defaults to false.

populate_user_metadata

no

Whether to populate the Elasticsearch user’s metadata with the values that are provided by the SAML attributes. Defaults to true.

allowed_clock_skew

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

If 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

signing.saml_messages

no

A list of SAML message types that should be signed, or * to sign all messages. Each element in the list should be the local name of a SAML XML Element. Supported element types are AuthnRequest, LogoutRequest and LogoutResponse. Defaults to *.

signing.key

no

Specifies the path to the PEM encoded private key to use for SAML message signing. signing.key and signing.keystore.path may not be used at the same time.

signing.secure_key_passphrase

no

(Secure) Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted.

signing.certificate

no

Specifies the path to the PEM encoded certificate (or certificate chain) that corresponds to the signing.key. This certificate must also be included in the Service Provider metadata, or manually configured within the IdP to allow for signature validation. May only be used if signing.key is set.

signing.keystore.path

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. signing.key and signing.keystore.path may not be used at the same time.

signing.keystore.type

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"

signing.keystore.alias

no

Specifies the alias of the key within the keystore that should be used for SAML message signing. Defaults to key.

signing.keystore.secure_password

no

(Secure) The password to the keystore.

signing.keystore.secure_key_password

no

(Secure) The password for the key in the keystore. Defaults to the keystore password.

SAML Realm Encryption Settings

If 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

encryption.key

no

Specifies the path to the PEM encoded private key to use for SAML message descryption. encryption.key and encryption.keystore.path may not be used at the same time.

encryption.secure_key_passphrase

no

(Secure) Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted.

encryption.certificate

no

Specifies the path to the PEM encoded certificate (or certificate chain) that is associated with the encryption.key. This certificate must also be included in the Service Provider metadata, or manually configured within the IdP to enable message encryption. May only be used if encryption.key is set.

encryption.keystore.path

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. encryption.key and encryption.keystore.path may not be used at the same time.

encryption.keystore.type

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"

encryption.keystore.alias

no

Specifies the alias of the key within the keystore that should be used for SAML message encryption. Defaults to key.

encryption.keystore.secure_password

no

(Secure) The password to the keystore.

encryption.keystore.secure_key_password

no

(Secure) The password for the key in the keystore.

SAML Realm SSL Settings

If 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

ssl.key

no

Specifies the path to the PEM encoded private key to use for http client authentication. ssl.key and ssl.keystore.path may not be used at the same time.

ssl.key_passphrase

no

Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted. May not be used with ssl.secure_key_passphrase

ssl.secure_key_passphrase

no

(Secure) Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted. May not be used with ssl.key_passphrase

ssl.certificate

no

Specifies the path to the PEM encoded certificate (or certificate chain) that goes with the key. May only be used if ssl.key is set.

ssl.certificate_authorities

no

Specifies the paths to the PEM encoded certificate authority certificates that should be trusted. ssl.certificate_authorities and ssl.truststore.path may not be used at the same time.

ssl.keystore.path

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. ssl.key and ssl.keystore.path may not be used at the same time.

ssl.keystore.type

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"

ssl.keystore.password

no

The password to the keystore. May not be used with ssl.keystore.secure_password.

ssl.keystore.secure_password

no

(Secure) The password to the keystore. May not be used with ssl.keystore.password.

ssl.keystore.key_password

no

The password for the key in the keystore. Defaults to the keystore password. May not be used with ssl.keystore.secure_key_password.

ssl.keystore.secure_key_password

no

(Secure) The password for the key in the keystore. Defaults to the keystore password. May not be used with ssl.keystore.key_password.

ssl.truststore.path

no

The path to the keystore that contains the certificates to trust. Must be either a Java Keystore (jks) or a PKCS#12 file. ssl.certificate_authorities and ssl.truststore.path may not be used at the same time.

ssl.truststore.type

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"

ssl.truststore.password

no

The password to the truststore. May not be used with ssl.truststore.secure_password.

ssl.truststore.secure_password

no

(Secure) The password to the truststore. May not be used with ssl.truststore.password.

ssl.verification_mode

no

One of full (verify the hostname and the certicate path), certificate (verify the certificate path, but not the hostname) or none (perform no verification). Defaults to full.

ssl.supported_protocols

no

Specifies the supported protocols for TLS/SSL.

ssl.cipher_suites

no

Specifies the cipher suites that should be supported.