[[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 <> 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 <>. 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. If not specified, all compatible key pairs from the keystore will be considered as candidate keys for decryption. | `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. Only a single password is supported. If you are using multiple decryption keys, then they cannot have individual passwords. |======================= ===== 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. |=======================