263 lines
21 KiB
Plaintext
263 lines
21 KiB
Plaintext
[[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. 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.
|
|
|=======================
|
|
|