[[saml-realm]]
=== SAML Authentication
{security} supports user authentication using SAML Single Sign On.
{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, {security} provides features in {kib} and {es} 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 {kib}, you should also configure
another realm, such as the <<native-realm, 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
<<saml-guide, Configuring Elasticsearch and Kibana to use SAML Single-Sign-On>>.

The remainder of this document will describe {es} specific configuration options
for SAML realms.


[[saml-settings]]
==== SAML Realm Settings

[cols="4,^3,10"]
|=======================
| 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. An Entity ID is
                                           a URI with a maximum length of 1024 characters. It can be a
                                           URL (`https://idp.example.com/`) or a URN (`urn:example.com:idp`)
                                           and can be found in the configuration or the SAML metadata
                                           of the 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
                                           {es} config directory.
                                           If a URL is provided, then it must be either a `file` URL or
                                           a `https` URL.
                                           {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 {es} `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 {kib} instance,
                                           e.g. `https://kibana.example.com/`
| `sp.acs`                    | yes      | The URL of the Assertion Consumer Service within {kib}.
                                           Typically this will be the "api/security/v1/saml" endpoint of
                                           your {kib} server,
                                           e.g. `https://kibana.example.com/api/security/v1/saml`
| `sp.logout`                 | no       | The URL of the Single Logout service within {kib}.
                                           Typically this will be the "logout" endpoint of
                                           your {kib} server,
                                           e.g. `https://kibana.example.com/logout`
| `attributes.principal`      | yes      | The Name of the SAML attribute that should be used as the
                                           {security} user's principal (username)
| `attributes.groups`         | no       | The Name of the SAML attribute that should be used to populate
                                           {security} user's groups
| `attributes.name`           | no       | The Name of the SAML attribute that should be used to populate
                                           {security} user's full name
| `attributes.mail`           | no       | The Name of the SAML attribute that should be used to populate
                                           {security} user's email address
| `attributes.dn`             | no       | The Name of the SAML attribute that should be used to populate
                                           {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 {es} 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 {es} 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
{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       | ({ref}/secure-settings.html[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. Must be specified if the keystore
                                                 contains more than one private key.
| `signing.keystore.secure_password` | no      | ({ref}/secure-settings.html[Secure]) The password to the keystore.
| `signing.keystore.secure_key_password` | no  | ({ref}/secure-settings.html[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 {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       | ({ref}/secure-settings.html[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 decryption. Must be specified if the keystore
                                                   contains more than one private key.
| `encryption.keystore.secure_password` | no     | ({ref}/secure-settings.html[Secure]) The password to the keystore.
| `encryption.keystore.secure_key_password` | no | ({ref}/secure-settings.html[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 {xpack}
{ref}/security-settings.html#ssl-tls-settings[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       | ({ref}/secure-settings.html[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       | ({ref}/secure-settings.html[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    | ({ref}/secure-settings.html[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      | ({ref}/secure-settings.html[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 {ref}/security-settings.html#ssl-tls-settings[`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.
|=======================

