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.

« File-based User Authentication Integrating with Other Authentication Systems »

› › ›

SAML Authentication

edit

SAML Authentication

edit

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

edit

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

edit

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

edit

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

edit

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`. + See `xpack.ssl.verification_mode` for a more detailed explanation of these values.
`ssl.supported_protocols`	no	Specifies the supported protocols for TLS/SSL.
`ssl.cipher_suites`	no	Specifies the cipher suites that should be supported.

« File-based User Authentication Integrating with Other Authentication Systems »