Security Settings in Elasticsearch

You configure xpack.security settings to enable anonymous access and perform message authentication, set up document and field level security, configure realms, and encrypt communications with SSL.

General Security Settings

xpack.security.enabled

Set to true (default) to enable X-Pack security on the node.

If set to false in elasticsearch.yml, X-Pack security is disabled. It also affects all Kibana instances that connect to this Elasticsearch instance; you do not need to disable X-Pack security in those kibana.yml files. For more information about disabling X-Pack security in specific Kibana instances, see Kibana Security Settings.

Default Password Security Settings

xpack.security.authc.accept_default_password
In elasticsearch.yml, set this to false to disable support for the default "changeme" password. For more information, see Disable Default Password Functionality.

Anonymous Access Settings

You can configure the following anonymous access settings in elasticsearch.yml. For more information, see Enabling Anonymous Access.

xpack.security.authc.anonymous.username
The username (principal) of the anonymous user. Defaults to _es_anonymous_user.
xpack.security.authc.anonymous.roles
The roles to associate with the anonymous user. Required.
xpack.security.authc.anonymous.authz_exception
When true, an HTTP 403 response is returned if the anonymous user does not have the appropriate permissions for the requested action. The user is not prompted to provide credentials to access the requested resource. When set to false, a HTTP 401 is returned and the user can provide credentials with the appropriate permissions to gain access. Defaults to true.

Document and Field Level Security Settings

You can set the following document and field level security settings in elasticsearch.yml. For more information, see Setting Up Document and Field Level Security.

xpack.security.dls_fls.enabled
Set to false to prevent document and field level security from being configured. Defaults to true.

Token Service Settings

You can set the following token service settings in elasticsearch.yml.

xpack.security.authc.token.enabled
Set to true to enable the built-in token service. Defaults to false.
xpack.security.authc.token.passphrase
A secure passphrase that must be the same on each node and greater than 8 characters in length. This passphrase is used to derive a cryptographic key with which the tokens will be encrypted and authenticated.
xpack.security.authc.token.timeout
The length of time that a token is valid for. By default this value is 20m or 20 minutes. The maximum value is 1 hour.

Realm Settings

You configure realm settings in the xpack.security.authc.realms namespace in elasticsearch.yml. For example:

xpack.security.authc.realms:

    realm1:
        type: native
        order: 0
        ...

    realm2:
        type: ldap
        order: 1
        ...

    realm3:
        type: active_directory
        order: 2
        ...
    ...

The valid settings vary depending on the realm type. For more information, see Setting Up Authentication.

Settings Valid for All Realms
type
The type of the realm: native, `ldap, active_directory, pki, or file. Required.
order
The priority of the realm within the realm chain. Defaults to Integer.MAX_VALUE.
enabled
Enable/disable the realm. Defaults to true.
File Realm Settings
cache.ttl
The time-to-live for cached user entries—user credentials are cached for this configured period of time. Defaults to 20m. Specify values using the standard Elasticsearch time units. Defaults to 20m.
cache.max_users
The maximum number of user entries that can live in the cache at a given time. Defaults to 100,000.
cache.hash_algo
(Expert Setting) The hashing algorithm that is used for the in-memory cached user credentials. See the Cache hash algorithms table for all possible values. Defaults to ssha256.
LDAP Realm Settings
url
An LDAP URL in the format ldap[s]://<server>:<port>. Required.
load_balance.type
The behavior to use when there are multiple LDAP URLs defined. For supported values see LDAP load balancing and failover types. Defaults to failover.
load_balance.cache_ttl
When using dns_failover or dns_round_robin as the load balancing type, this setting controls the amount of time to cache DNS lookups. Defaults to 1h.
bind_dn
The DN of the user that will be used to bind to the LDAP and perform searches. Only applicable in user search mode. If this is not specified, an anonymous bind will be attempted. Defaults to Empty.
bind_password
The password for the user that will be used to bind to the LDAP. Defaults to Empty.
user_dn_templates
The DN template that replaces the user name with the string {0}. This element is multivalued; you can specify multiple user contexts. Required to operate in user template mode. Not valid if user_search.base_dn is specified. For more information on the different modes, see LDAP realms.
user_group_attribute
Specifies the attribute to examine on the user for group membership. The default is memberOf. This setting will be ignored if any group_search settings are specified. Defaults to memberOf.
user_search.base_dn
Specifies a container DN to search for users. Required to operated in user search mode. Not valid if `user_dn_templates is specified. For more information on the different modes, see LDAP realms.
user_search.scope
The scope of the user search. Valid values are sub_tree, one_level or base. one_level only searches objects directly contained within the base_dn. sub_tree searches all objects contained under base_dn. base specifies that the base_dn is the user object, and that it is the only user considered. Defaults to sub_tree.
user_search.filter
Specifies the filter used to search the directory in attempt to match an entry with the username provided by the user. Defaults to (uid={0}). {0} is substituted with the username provided when searching.
user_search.attribute
This setting is deprecated; use user_search.filter instead. The attribute to match with the username presented to. Defaults to uid.
user_search.pool.enabled
Enables or disables connection pooling for user search. When disabled a new connection is created for every search. The default is true when bind_dn is provided.
user_search.pool.size
The maximum number of connections to the LDAP server to allow in the connection pool. Defaults to 20.
user_search.pool.initial_size
The initial number of connections to create to the LDAP server on startup. Defaults to 0.
user_search.pool.health_check.enabled
Flag to enable or disable a health check on LDAP connections in the connection pool. Connections are checked in the background at the specified interval. Defaults to true.
user_search.pool.health_check.dn
The distinguished name to be retrieved as part of the health check. Defaults to the value of bind_dn if present, and if not falls back to user_search.base_dn.
user_search.pool.health_check.interval
The interval to perform background checks of connections in the pool. Defaults to 60s.
group_search.base_dn
The container DN to search for groups in which the user has membership. When this element is absent, Security searches for the attribute specified by user_group_attribute set on the user in order to determine group membership.
group_search.scope
Specifies whether the group search should be sub_tree, one_level or base. one_level only searches objects directly contained within the base_dn. sub_tree searches all objects contained under base_dn. base specifies that the base_dn is a group object, and that it is the only group considered. Defaults to sub_tree.
group_search.filter
When not set, the realm searches for group, groupOfNames, groupOfUniqueNames, or posixGroup with the attributes member, memberOf, or memberUid. Any instance of {0} in the filter is replaced by the user attribute defined in group_search.user_attribute.
group_search.user_attribute
Specifies the user attribute that will be fetched and provided as a parameter to the filter. If not set, the user DN is passed into the filter. Defaults to Empty.
unmapped_groups_as_roles
Takes a boolean variable. When this element is set to true, the names of any LDAP groups that are not referenced in a role-mapping file are used as role names and assigned to the user. Defaults to false.
files.role_mapping
The location for the YAML role mapping configuration file. Defaults to CONFIG_DIR/x-pack/role_mapping.yml.
follow_referrals
Boolean value that specifies whether Securityshould follow referrals returned by the LDAP server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (e.g. search). Defaults to true.
metadata
A list of additional LDAP attributes that should be loaded from the LDAP server and stored in the authenticated user’s metadata field.
timeout.tcp_connect
The TCP connect timeout period for establishing an LDAP connection. An s at the end indicates seconds, or ms indicates milliseconds. Defaults to 5s (5 seconds ).
timeout.tcp_read
The TCP read timeout period after establishing an LDAP connection. An s at the end indicates seconds, or ms indicates milliseconds. Defaults to 5s (5 seconds ).
timeout.ldap_search
The LDAP Server enforced timeout period for an LDAP search. An s at the end indicates seconds, or ms indicates milliseconds. Defaults to 5s (5 seconds ).
ssl.key
Path to a PEM encoded file containing the private key.
ssl.key_passphrase
The passphrase that will be used to decrypt the private key. This value is optional as the key may not be encrypted.
ssl.certificate
Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented to clients when they connect.
ssl.certificate_authorities
List of paths to PEM encoded certificate files that should be trusted.
ssl.keystore.path
The path to the Java Keystore file that contains a private key and certificate. ssl.key and ssl.keystore.path may not be used at the same time.
ssl.keystore.password
The password to the keystore.
ssl.keystore.key_password
The password for the key in the keystore. Defaults to the keystore password.
ssl.truststore.path
The path to the Java Keystore file that contains the certificates to trust. ssl.certificate_authorities and ssl.truststore.path may not be used at the same time.
ssl.truststore.password
The password to the truststore.
ssl.verification_mode
Indicates the type of verification when using ldaps to protect against man in the middle attacks and certificate forgery. Values are none, certificate, and full. Defaults to the value of xpack.ssl.verification_mode.
ssl.supported_protocols
Supported protocols with versions. Defaults to the value of xpack.ssl.supported_protocols.

ssl.cipher_suites Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to the value of xpack.ssl.cipher_suites.

cache.ttl
Specifies the time-to-live for cached user entries (a user and its credentials are cached for this period of time). Use the standard Elasticsearch time units). Defaults to 20m.
cache.max_users
Specifies the maximum number of user entries that the cache can contain. Defaults to 100000.
cache.hash_algo
(Expert Setting) Specifies the hashing algorithm that is used for the in-memory cached user credentials (see Cache hash algorithms table for all possible values). Defaults to ssha256.
Active Directory Realm Settings
url
A URL in the format ldap[s]://<server>:<port>. Defaults to ldap://<domain_name>:389.
load_balance.type
The behavior to use when there are multiple LDAP URLs defined. For supported values see load balancing and failover types. Defaults to failover.
load_balance.cache_ttl
When using dns_failover or dns_round_robin as the load balancing type, this setting controls the amount of time to cache DNS lookups. Defaults to 1h.
domain_name
The domain name of Active Directory. The cluster can derive the URL and user_search_dn fields from values in this element if those fields are not otherwise specified. Required.
bind_dn
The DN of the user that will be used to bind to Active Directory and perform searches. Defaults to Empty.
bind_password
The password for the user that will be used to bind to Active Directory. Defaults to Empty.
unmapped_groups_as_roles
Takes a boolean variable. When this element is set to true, the names of any LDAP groups that are not referenced in a role-mapping file are used as role names and assigned to the user. Defaults to false.
files.role_mapping
The location for the YAML role mapping configuration file. Defaults to CONFIG_DIR/x-pack/role_mapping.yml.
user_search.base_dn
The context to search for a user. Defaults to the root of the Active Directory domain.
user_search.scope
Specifies whether the user search should be sub_tree, one_level or base. one_level only searches users directly contained within the base_dn. sub_tree searches all objects contained under base_dn. base specifies that the base_dn is a user object, and that it is the only user considered. Defaults to sub_tree.
user_search.filter
Specifies a filter to use to lookup a user given a username. The default filter looks up user objects with either sAMAccountName or userPrincipalName.
user_search.upn_filter
Specifies a filter to use to lookup a user given a user principal name. The default filter looks up user objects with a matching userPrincipalName. If specified, this must be a valid LDAP user search filter, for example (&(objectClass=user)(userPrincipalName={1})). {1} is the full user principal name provided by the user.
user_search.down_level_filter
Specifies a filter to use to lookup a user given a down level logon name (DOMAIN\user). The default filter looks up user objects with a matching sAMAccountName in the domain provided. If specified, this must be a valid LDAP user search filter, for example (&(objectClass=user)(sAMAccountName={0})).
user_search.pool.enabled
Enables or disables connection pooling for user search. When disabled a new connection is created for every search. The default is true when bind_dn is provided.
user_search.pool.size
The maximum number of connections to the Active Directory server to allow in the connection pool. Defaults to 20.
user_search.pool.initial_size
The initial number of connections to create to the Active Directory server on startup. Defaults to 0.
user_search.pool.health_check.enabled
Flag to enable or disable a health check on Active Directory connections in the connection pool. Connections are checked in the background at the specified interval. Defaults to true.
user_search.pool.health_check.dn
The distinguished name to be retrieved as part of the health check. Defaults to the value of bind_dn if it is a distinguished name.
user_search.pool.health_check.interval
The interval to perform background checks of connections in the pool. Defaults to 60s.
group_search.base_dn
The context to search for groups in which the user has membership. Defaults to the root of the Active Directory domain.
group_search.scope
Specifies whether the group search should be sub_tree, one_level or base. one_level searches for groups directly contained within the base_dn. sub_tree searches all objects contained under base_dn. base specifies that the base_dn is a group object, and that it is the only group considered. Defaults to sub_tree.
metadata
A list of additional LDAP attributes that should be loaded from the LDAP server and stored in the authenticated user’s metadata field.
timeout.tcp_connect
The TCP connect timeout period for establishing an LDAP connection. An s at the end indicates seconds, or ms indicates milliseconds. Defaults to 5s (5 seconds ).
timeout.tcp_read
The TCP read timeout period after establishing an LDAP connection. An s at the end indicates seconds, or ms indicates milliseconds. Defaults to 5s (5 seconds ).
timeout.ldap_search
The LDAP Server enforced timeout period for an LDAP search. An s at the end indicates seconds, or ms indicates milliseconds. Defaults to 5s (5 seconds ).
ssl.key
Path to the PEM encoded file containing the private key.
ssl.key_passphrase
The passphrase that will be used to decrypt the private key. This value is optional as the key may not be encrypted.
ssl.certificate
Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented to clients when they connect.
ssl.certificate_authorities
List of paths to PEM encoded certificate files that should be trusted.
ssl.keystore.path
The path to the Java Keystore file that contains a private key and certificate.
ssl.keystore.password
The password to the keystore.
ssl.keystore.key_password
The password for the key in the keystore. Defaults to the keystore password.
ssl.truststore.path
The path to the Java Keystore file that contains the certificates to trust.
ssl.truststore.password
The password to the truststore.
ssl.verification_mode
Indicates the type of verification when using ldaps to protect against man in the middle attacks and certificate forgery. Values are none, certificate, and full. Defaults to the value of xpack.ssl.verification_mode.
ssl.supported_protocols
Supported protocols with versions. Defaults to the value of xpack.ssl.supported_protocols.

ssl.cipher_suites Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to the value of xpack.ssl.cipher_suites.

cache.ttl
Specifies the time-to-live for cached user entries (user credentials are cached for this configured period of time). Use the standard Elasticsearch time units). Defaults to 20m.
cache.max_users
Specifies the maximum number of user entries that the cache can contain. Defaults to 100000.
cache.hash_algo
(Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see Cache hash algorithms table for all possible values). Defaults to ssha256.
PKI Realm Settings
username_pattern
The regular expression pattern used to extract the username from the certificate DN. The first match group is the used as the username. Defaults to CN=(.*?)(?:,\|$)
certificate_authorities
List of PEM certificate files that should be used to authenticate a user’s certificate as trusted. Defaults to the trusted certificates configured for SSL. See the SSL settings section of the PKI realm documentation for more information. This setting may not be used with truststore.path.
truststore.path
The path of a truststore to use. Defaults to the trusted certificates configured for SSL. See the SSL settings section of the PKI realm documentation for more information. This setting may not be used with certificate_authorities.
truststore.password
The password for the truststore. Must be provided if truststore.path is set.
truststore.algorithm
Algorithm for the truststore. Defaults to SunX509.
files.role_mapping
Specifies the location of the YAML role mapping configuration file. Defaults to CONFIG_DIR/x-pack/role_mapping.yml.

Default TLS/SSL Settings

You can configure the following TLS/SSL settings in elasticsearch.yml. For more information, see Encrypting Communications. These settings will be used for all of X-Pack unless they have been overridden by more specific settings such as those for HTTP or Transport.

xpack.ssl.supported_protocols
Supported protocols with versions. Valid protocols: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2. Defaults to TLSv1.2, TLSv1.1, TLSv1.
xpack.ssl.client_authentication
Controls the server’s behavior in regard to requesting a certificate from client connections. Valid values are required, optional, and none. required forces a client to present a certificate, while optional requests a client certificate but the client is not required to present one. Defaults to required.
xpack.ssl.verification_mode
Controls the verification of certificates. Valid values are none, certificate, and full. Defaults to full.

xpack.ssl.cipher_suites Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_128_CBC_SHA.

Default TLS/SSL Key and Trusted Certificate Settings

The following settings are used to specify a private key, certificate, and the trusted certificates that should be used when communicating over an SSL/TLS connection. If none of the settings below are specified, this will default to the X-Pack defaults. If no trusted certificates are configured, the default certificates that are trusted by the JVM will be trusted along with the certificate(s) from the key settings. The key and certificate must be in place for connections that require client authentication or when acting as a SSL enabled server.

PEM Encoded Files

When using PEM encoded files, use the following settings:

xpack.ssl.key
Path to the PEM encoded file containing the private key.
xpack.ssl.key_passphrase
The passphrase that will be used to decrypt the private key. This value is optional as the key may not be encrypted.
xpack.ssl.certificate
Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented to clients when they connect.
xpack.ssl.certificate_authorities
List of paths to the PEM encoded certificate files that should be trusted.
Java Keystore Files

When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings:

xpack.ssl.keystore.path
Path to the keystore that holds the private key and certificate.
xpack.ssl.keystore.password
Password to the keystore.
xpack.ssl.keystore.key_password
Password for the private key in the keystore. Defaults to the same value as xpack.ssl.keystore.password.
xpack.ssl.truststore.path
Path to the truststore file.
xpack.ssl.truststore.password
Password to the truststore.

HTTP TLS/SSL Settings

You can configure the following TLS/SSL settings. If the settings are not configured, the Default TLS/SSL Settings are used.

xpack.security.http.ssl.enabled
Used to enable or disable TLS/SSL. The default is false.
xpack.security.http.ssl.supported_protocols
Supported protocols with versions. Valid protocols: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2. Defaults to TLSv1.2, TLSv1.1, TLSv1. Defaults to the value of xpack.ssl.supported_protocols.
xpack.security.http.ssl.client_authentication
Controls the server’s behavior in regard to requesting a certificate from client connections. Valid values are required, optional, and none. required forces a client to present a certificate, while optional requests a client certificate but the client is not required to present one. Defaults to none.
xpack.security.http.ssl.cipher_suites
Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to the value of xpack.ssl.cipher_suites.

HTTP TLS/SSL Key and Trusted Certificate Settings

The following settings are used to specify a private key, certificate, and the trusted certificates that should be used when communicating over an SSL/TLS connection. If none of the settings below are specified, the Default TLS/SSL Settings are used. A private key and certificate must be configured. If none of the settings below are specified, the Default TLS/SSL Settings are used.

PEM Encoded Files

When using PEM encoded files, use the following settings:

xpack.security.http.ssl.key
Path to a PEM encoded file containing the private key.
xpack.security.http.ssl.key_passphrase
The passphrase that will be used to decrypt the private key. This value is optional as the key may not be encrypted.
xpack.security.http.ssl.certificate
Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented when requested.
xpack.security.http.ssl.certificate_authorities
List of paths to the PEM encoded certificate files that should be trusted.

Java Keystore Files

When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings:

xpack.security.http.ssl.keystore.path
Path to the keystore that holds the private key and certificate.
xpack.security.http.ssl.keystore.password
Password to the keystore.
xpack.security.http.ssl.keystore.key_password
Password for the private key in the keystore. Defaults to the same value as xpack.security.http.ssl.keystore.password.
xpack.security.http.ssl.truststore.path
Path to the truststore file.
xpack.security.http.ssl.truststore.password
Password to the truststore.

Transport TLS/SSL Settings

You can configure the following TLS/SSL settings. If the settings are not configured, the Default TLS/SSL Settings are used.

xpack.security.transport.ssl.enabled
Used to enable or disable TLS/SSL. The default is false.
xpack.security.transport.ssl.supported_protocols
Supported protocols with versions. Valid protocols: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2. Defaults to TLSv1.2, TLSv1.1, TLSv1. Defaults to the value of xpack.ssl.supported_protocols.
xpack.security.transport.ssl.client_authentication
Controls the server’s behavior in regard to requesting a certificate from client connections. Valid values are required, optional, and none. required forces a client to present a certificate, while optional requests a client certificate but the client is not required to present one. Defaults to the value of xpack.ssl.client_authentication.
xpack.security.transport.ssl.verification_mode
Controls the verification of certificates. Valid values are none, certificate, and full. Defaults to the value of xpack.ssl.verification_mode.
xpack.security.transport.ssl.cipher_suites
Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Defaults to the value of xpack.ssl.cipher_suites.

Transport TLS/SSL Key and Trusted Certificate Settings

The following settings are used to specify a private key, certificate, and the trusted certificates that should be used when communicating over an SSL/TLS connection. If none of the settings below are specified, the Default TLS/SSL Settings are used. A private key and certificate must be configured. If none of the settings below are specified, the Default TLS/SSL Settings are used.

PEM Encoded Files

When using PEM encoded files, use the following settings:

xpack.security.transport.ssl.key
Path to a PEM encoded file containing the private key.
xpack.security.transport.ssl.key_passphrase
The passphrase that will be used to decrypt the private key. This value is optional as the key may not be encrypted.
xpack.security.transport.ssl.certificate
Path to a PEM encoded file containing the certificate (or certificate chain) that will be presented when requested.
xpack.security.transport.ssl.certificate_authorities
List of paths to the PEM encoded certificate files that should be trusted.

Java Keystore Files

When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings:

xpack.security.transport.ssl.keystore.path
Path to the keystore that holds the private key and certificate.
xpack.security.transport.ssl.keystore.password
Password to the keystore.
xpack.security.transport.ssl.keystore.key_password
Password for the private key in the keystore. Defaults to the same value as xpack.security.transport.ssl.keystore.password.
xpack.security.transport.ssl.truststore.path
Path to the truststore file.
xpack.security.transport.ssl.truststore.password
Password to the truststore.
Transport Profile TLS/SSL Settings

The same settings that are available for the default transport are also available for each transport profile. By default, the settings for a transport profile will be the same as the default transport unless they are specified.

As an example, lets look at the enabled setting. For the default transport this is xpack.security.transport.ssl.enabled. In order to use this setting in a transport profile, use the prefix transport.profiles.$PROFILE.xpack.security. and append the portion of the setting after xpack.security.transport.. For the enabled setting, this would be transport.profiles.$PROFILE.xpack.security.ssl.enabled.

IP Filtering Settings

You can configure the following settings for IP filtering.

xpack.security.transport.filter.allow
List of IP addresses to allow.
xpack.security.transport.filter.deny
List of IP addresses to deny.
xpack.security.http.filter.allow
List of IP addresses to allow just for HTTP.
xpack.security.http.filter.deny
List of IP addresses to deny just for HTTP.
transport.profiles.$PROFILE.xpack.security.filter.allow
List of IP addresses to allow for this profile.
transport.profiles.$PROFILE.xpack.security.filter.deny
List of IP addresses to deny for this profile.