This is an older version of Search Guard. Switch to Latest version
SAML Authentication for Elasticsearch
- Activating SAML
- Running multiple authentication domains
- Identity provider metadata
- Idp and service provider entity ID
- Kibana settings
- Username and Role attributes
- Request signing
- Exchange key settings
- Using only certain sections of a SAML user name
- TLS settings
- Minimal configuration example
- Kibana configuration
- IdP initated SSO
Search Guard supports user authentication via SAML Single Sign-On. Search Guard implements the Web Browser SSO profile of the SAML 2.0 protocol.
This profile is intended to be used with web browsers. It is not a general-purpose way of authenticating users against Search Guard, so it is not meant for using it with other REST clients. The primary use case is to support Kibana Single Sign-On.
If you have problems configuring SAML please refer to the SAML troubleshooting guide.
To use SAML for authentication, you need to configure a respective authentication domain in the
authc section of
sg_config. Since SAML works solely on the HTTP layer, you do not need any
authentication_backend and can set it to noop. Place all SAML specific configuration options in this chapter in the
config section of the SAML HTTP authenticator like:
authc: saml: http_enabled: true order: 1 http_authenticator: type: saml challenge: true config: idp: metadata_file: okta.xml ... authentication_backend: type: noop
Once you have configured SAML in
sg_config, you need to also activate it in Kibana.
Running multiple authentication domains
We recommend adding at least one other authentication domain, such as LDAP or the internal user database, to support API access to Elasticsearch without SAML. For Kibana and the internal Kibana server user, it is also required to add another authentication domain that supports basic authentication. This authentication domain should be placed first in the chain, and the
challenge flag has to be set to
authc: basic_internal_auth_domain: http_enabled: true order: 0 http_authenticator: type: basic challenge: false authentication_backend: type: internal saml_auth_domain: http_enabled: true order: 1 http_authenticator: type: 'saml' challenge: true config: ... authentication_backend: type: noop
Identity provider metadata
A SAML IdP provides a SAML 2.0 metadata file describing the IdPs capabilities and configuration. Search Guard can read IdP metadata either from a URL or a file. Which way to choose depends on your IdP and your preferences. The SAML 2.0 metadata file is mandatory.
|idp.metadata_file||The path to the SAML 2.0 metadata file of your IdP. Place the metadata file in the
|idp.metadata_url||The SAML 2.0 metadata URL of your IdP. Mandatory if
Idp and service provider entity ID
An entity ID is a globally unique name for a SAML entity, either an IdP or a Service Provider (SP). The IdP entity ID is usually provided by your IdP. The SP entity ID is the name of the configured application or client in your IdP. We recommend to add a new application/client for Kibana and use the URL of your Kibana installation as SP entity id.
|idp.entity_id||The entity ID of your IdP. Mandatory.|
|sp.entity_id||The entity ID of the service provider. Mandatory.|
The Web Browser SSO profile works by exchanging information via HTTP GET or POST. For example, after you log in to your IdP, it will issue an HTTP POST back to Kibana containing the
SAML Response. You need to configure the base URL of your Kibana installation where the HTTP requests are being sent to.
|kibana_url||The Kibana base URL. Mandatory.|
Username and Role attributes
Subjects (a.k.a usernames) are usually stored in the NameID element of a SAML response:
<saml2:Subject> <saml2:NameID>admin</saml2:NameID> ... </saml2:Subject>
If your IdP is compliant with the SAML 2.0 specification you do not need to set anything special. If your IdP uses a different element name, you can also specify its name explicitly.
Role attributes are optional. However, most IdPs can be configured to add roles in the SAML assertions as well. You can use these roles for mapping users to Search Guard roles. Usually, the
Role element is used for that, e.g.
<saml2:Attribute Name='Role'> <saml2:AttributeValue >Everyone</saml2:AttributeValue> <saml2:AttributeValue >Admins</saml2:AttributeValue> </saml2:Attribute>
If you want to extract roles from the SAML response, you need to specify the element name that contains the roles.
|subject_key||The attribute in the SAML response where the subject is stored. Optional. If not configured, the NameID attribute is used.|
|roles_key||The attribute in the SAML response where the roles are stored. Optional. If not configured, no roles will be used.|
Requests from Search Guard to the IdP can optionally be signed. Use the following settings to configure request signing:
|sp.signature_private_key||The private key used to sign the requests. Optional. If not provided, requests are not signed.|
|sp.signature_algorithm||The algorithm used to sign the requests. See below for possible values.|
Search Guard supports the following signature algorithms:
Usually, IdPs provide information about their individual logout URL in their SAML 2.0 metadata. If this is the case, Search Guard will make use of them and render the correct logout link in Kibana. If your IdP does not support an explicit logout, you can force a re-login when the user visits Kibana again:
|sp.forceAuthn||Force a re-login even if the user has an active session with the IdP|
At the moment Search Guard only supports the
HTTP-Redirect logout binding. Please make sure this is configured correctly in your IdP.
Exchange key settings
SAML, unlike other protocols like JWT or Basic Authentication, is not meant to be used for exchanging user credentials with each request. Therefore Search Guard trades the heavy-weight SAML response for a light-weight JSON web token that stores the validated user attributes. This token is signed by an exchange key that you can choose freely. Note that when you change this key, all tokens signed with it will become invalid immediately.
|exchange_key||The key to sign the token. The algorithm is HMAC256, so it should have at least 32 characters.|
Using only certain sections of a SAML user name
In some cases, the user name in a SAML assertion might be more complex than needed or wanted. For example, a SAML user name could be specified as an email address like
[email protected]. The
subject_pattern option gives you the possibility to only use the local part (i.e.,
exampleuser) as the user name inside Search Guard.
subject_pattern you specify a regular expression that defines the structure of an expected user name. You can then use capturing groups (i.e., sections enclosed in round parentheses;
(...)) to use only a certain part of the name supplied by the SAML assertion as the Search Guard user name.
authc: saml: http_enabled: true order: 1 http_authenticator: type: saml challenge: true config: subject_pattern: "^(.+)@example\.com$" ...
In this example,
(.+) is the capturing group, i.e., at least one character. This group must be followed by the string
@example.com, which must be present, but will not be part of the resulting user name in Search Guard. If you try to login with a subject that does not match this pattern (e.g.
[email protected]), login will fail.
You can use all the pattern features which the Java
Pattern class supports. See the official documentation for details.
Keep in mind that all capturing groups are used for constructing the user name. If you need grouping only because you want to apply a pattern quantifier or operator, you should use non-capturing groups:
Example for using capturing groups and non-capturing groups:
In this example, the group around
org is required to use the alternative operator
|. But it must be non-capturing, because otherwise it would show up in the user name.
You can however also use several capturing groups if you want to use these groups for the user name:
If you are loading the IdP metadata from a URL, it is recommended to use SSL/TLS. If you use an external IdP like Okta or Auth0 that uses a trusted certificate, you usually do not need to configure anything. If you host the IdP yourself and use your own root CA, you can customize the TLS settings as follows. These settings are only used for loading SAML metadata over https.
|idp.enable_ssl||Whether to enable the custom TLS configuration or not. Default: false (JDK settings are used)|
|idp.verify_hostnames||Whether to verify the hostnames of the server’s TLS certificate or not|
authc: saml: http_enabled: true order: 1 http_authenticator: type: saml challenge: true config: idp: enable_ssl: true verify_hostnames: true ... authentication_backend: type: noop
Configure the root CA used for validating the IdP TLS certificate by setting one of the following configuration options:
config: idp: pemtrustedcas_filepath: path/to/trusted_cas.pem
config: idp: pemtrustedcas_content: |- MIID/jCCAuagAwIBAgIBATANBgkqhkiG9w0BAQUFADCBjzETMBEGCgmSJomT8ixk ARkWA2NvbTEXMBUGCgmSJomT8ixkARkWB2V4YW1wbGUxGTAXBgNVBAoMEEV4YW1w bGUgQ29tIEluYy4xITAfBgNVBAsMGEV4YW1wbGUgQ29tIEluYy4gUm9vdCBDQTEh ...
|idp.pemtrustedcas_filepath||Path to the PEM file containing the root CA(s) of your IdP. The files must be placed under the Elasticsearch
|idp.pemtrustedcas_content||The root CA content of your IdP server. Cannot be used when
Search Guard can use TLS client authentication when fetching the IdP metadata. If enabled, Search Guard sends a TLS client certificate to the IdP for each metadata request. Use the following keys to configure client authentication:
|idp.enable_ssl_client_auth||Whether to send a client certificate to the IdP server or not. Default: false|
|idp.pemcert_filepath||Path to the PEM file containing the client certificate. The file must be placed under the Elasticsearch
|idp.pemcert_content||The content of the client certificate. Cannot be used when
|idp.pemkey_filepath||Path to the private key of the client certificate. The file must be placed under the Elasticsearch
|idp.pemkey_content||The content of the private key of your certificate. Cannot be used when
|idp.pemkey_password||The password of your private key, if any.|
Enabled ciphers and protocols
You can limit the allowed ciphers and TLS protocols for the IdP connection. For example, you can only enable strong ciphers and limit the TLS versions to the most recent ones.
|idp.enabled_ssl_ciphers||Array, enabled TLS ciphers. Only Java format is supported.|
|idp.enabled_ssl_protocols||Array, enabled TLS protocols. Only Java format is supported.|
Note: By default, Search Guard disables
TLSv1 because it is insecure. If you need to use
TLSv1 and you know what you are doing, you can re-enable it like:
enabled_ssl_protocols: - "TLSv1" - "TLSv1.1" - "TLSv1.2"
Minimal configuration example
authc: saml: http_enabled: true order: 1 http_authenticator: type: saml challenge: true config: idp: metadata_file: metadata.xml entity_id: http://idp.example.com/ sp: entity_id: https://kibana.example.com kibana_url: https://kibana.example.com:5601/ roles_key: Role exchange_key: 'peuvgOLrjzuhXf ...' authentication_backend: type: noop
Since most of the SAML specific configuration is done in Search Guard, just activate SAML in your
kibana.yml by adding:
It is also required to set the isSameSite=None to enable Kibana to send the cookie in a third-party context. Read more. The setting requires HTTPS.
searchguard.cookie.isSameSite: None searchguard.cookie.secure: true
In addition the Kibana endpoint for validating the SAML assertions must be whitelisted:
If you use the logout POST binding, you also need to whitelist the logout endpoint:
server.xsrf.whitelist: ["/searchguard/saml/acs", "/searchguard/saml/logout"]
IdP initated SSO
To use IdP initiated SSO, in your IdP, set the Assertion Consumer Service endpoint to:
Then add this endpoint to the xsrf whitelist in kibana.yml:
server.xsrf.whitelist: ["/searchguard/saml/acs/idpinitiated", "/searchguard/saml/acs", "/searchguard/saml/logout"]