elasticsearch/docs/reference/settings/security-settings.asciidoc

[role="xpack"]
[[security-settings]]
=== Security settings in {es}
++++
<titleabbrev>Security settings</titleabbrev>
++++

By default, {security} is disabled when you have a basic or trial license. To
enable {security}, use the `xpack.security.enabled` setting.

You configure `xpack.security` settings  to
<<anonymous-access-settings, enable anonymous access>>
and perform message authentication,
<<field-document-security-settings, set up document and field level security>>,
<<realm-settings, configure realms>>,
<<ssl-tls-settings, encrypt communications with SSL>>, and
<<auditing-settings, audit security events>>.

All of these settings can be added to the `elasticsearch.yml` configuration file,
with the exception of the secure settings, which you add to the {es} keystore.
For more information about creating and updating the {es} keystore, see
<<secure-settings>>.

[float]
[[general-security-settings]]
==== General security settings
`xpack.security.enabled`::
Set to `true` to enable {security} on the node. +
+
If set to `false`, which is the default value for basic and trial licenses,
{security} is disabled. It also affects all {kib} instances that connect to this
{es} instance; you do not need to disable {security} in those `kibana.yml` files.
For more information about disabling {security} in specific {kib} instances, see  {kibana-ref}/security-settings-kb.html[{kib} security settings].

`xpack.security.hide_settings`::
A comma-separated list of settings that are omitted from the results of the
<<cluster-nodes-info,cluster nodes info API>>. You can use wildcards to include
multiple settings in the list.  For example, the following value hides all the
settings for the ad1 realm: `xpack.security.authc.realms.ad1.*`. The API already
omits all `ssl` settings, `bind_dn`, and `bind_password` due to the
sensitive nature of the information.

[float]
[[password-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.

[float]
[[anonymous-access-settings]]
==== Anonymous access settings
You can configure the following anonymous access settings in
`elasticsearch.yml`.  For more information, see {xpack-ref}/anonymous-access.html[
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`.

[float]
[[field-document-security-settings]]
==== Document and field level security settings

You can set the following document and field level security
settings in `elasticsearch.yml`. For more information, see
{xpack-ref}/field-and-document-access-control.html[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`.

[float]
[[token-service-settings]]
==== Token service settings

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

`xpack.security.authc.token.enabled`::
Set to `false` to disable the built-in token service. Defaults to `true` unless
 `xpack.security.http.ssl.enabled` is `false`. This prevents sniffing the token
  from a connection over plain http.

`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.

[float]
[[realm-settings]]
==== Realm settings
You configure realm settings in the `xpack.security.authc.realms`
namespace in `elasticsearch.yml`. For example:

[source,yaml]
----------------------------------------
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 {xpack-ref}/setting-up-authentication.html[Setting up authentication].

[float]
[[ref-realm-settings]]
===== 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. Realms with a lower order are
consulted first. Although not required, use of this setting is strongly
recommended when you configure multiple realms. Defaults to `Integer.MAX_VALUE`.

`enabled`::
Indicates whether a realm is enabled. You can use this setting to disable a
realm without removing its configuration information. Defaults to `true`.

[[ref-native-settings]]
[float]
===== Native realm settings

For a native realm, the `type` must be set to `native`. In addition to the 
<<ref-realm-settings,settings that are valid for all realms>>, you can specify  
the following optional settings: 

`cache.ttl`:: The time-to-live for cached user entries. A user and a hash of its 
credentials are cached for this period of time. Specify the time period using 
the standard {es} <<time-units,time units>>. Defaults to `20m`.

`cache.max_users`:: The maximum number of user entries that can live in the 
cache at any given time. Defaults to 100,000.

`cache.hash_algo`:: (Expert Setting) The hashing algorithm that is used for the 
in-memory cached user credentials. For possible values, see 
{xpack-ref}/controlling-user-cache.html[Cache hash algorithms]. Defaults to 
`ssha256`.


[[ref-users-settings]]

[float]
===== File realm settings

The `type` setting must be set to `file`. In addition to the 
<<ref-realm-settings,settings that are valid for all realms>>, you can specify  
the following settings: 

`cache.ttl`::
The time-to-live for cached user entries. A user and a hash of its credentials 
are cached for this configured period of time. Defaults to `20m`. Specify values 
using the standard {es} {ref}/common-options.html#time-units[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 {xpack-ref}/controlling-user-cache.html#controlling-user-cache[Cache hash algorithms] table for
all possible values. Defaults to `ssha256`.

[[ref-ldap-settings]]
[float]
===== LDAP realm settings

The `type` setting must be set to `ldap`. In addition to the 
<<ref-realm-settings>>, you can specify the following settings: 

`url`:: Specifies one or more LDAP URLs in the format  
`ldap[s]://<server>:<port>`. Multiple URLs can be defined using a comma 
separated value or array syntax: `[ "ldaps://server1:636", "ldaps://server2:636" ]`. 
`ldaps` and `ldap` URL protocols cannot be mixed in the same realm. Required.

`load_balance.type`::
The behavior to use when there are multiple LDAP URLs defined. For supported
values see <<load-balancing,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 is used to bind to the LDAP and perform searches.
Only applicable in user search mode.
If not specified, an anonymous bind is attempted.
Defaults to Empty. Due to its potential security impact, `bind_dn` is not 
exposed via the <<cluster-nodes-info,nodes info API>>.

`bind_password`::
deprecated[6.3] Use `secure_bind_password` instead. The password for the user 
that is used to bind to the LDAP directory.
Defaults to Empty. Due to its potential security impact, `bind_password` is not 
exposed via the <<cluster-nodes-info,nodes info API>>.


`secure_bind_password` (<<secure-settings,Secure>>)::
The password for the user that is used to bind to the LDAP directory.
Defaults to Empty.

`user_dn_templates`::
The DN template that replaces the user name with the string `{0}`.
This setting is multivalued; you can specify multiple user contexts.
Required to operate in user template mode. If `user_search.base_dn` is specified, 
this setting is not valid. For more information on
the different modes, see {xpack-ref}/ldap-realm.html[LDAP realms].
+
--
NOTE: If any settings starting with `user_search` are specified, the 
`user_dn_templates` settings are ignored.

--

`user_group_attribute`::
Specifies the attribute to examine on the user for group membership.
If any `group_search` settings are specified, this setting is ignored. Defaults 
to `memberOf`.

`user_search.base_dn`::
Specifies a container DN to search for users. Required
to operated in user search mode. If `user_dn_templates` is specified, this 
setting is not valid. For more information on
the different modes, see {xpack-ref}/ldap-realm.html[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 attempts 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`::
deprecated[5.6] Use `user_search.filter` instead.
The attribute to match with the username sent with the request. Defaults to `uid`.

`user_search.pool.enabled`::
Enables or disables connection pooling for user search. If set to `false`, a new 
connection is created for every search. The
default is `true` when `bind_dn` is set.

`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`. If the LDAP server is down, values greater than `0` could cause 
startup failures.

`user_search.pool.health_check.enabled`::
Enables or disables 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 that is retrieved as part of the health check.
Defaults to the value of `bind_dn` if present; 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`:: 
Specifies a filter to use to look up a group. 
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 is 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`::
If set to `true`, the names of any unmapped LDAP groups are used as role names 
and assigned to the user. A group is considered to be _unmapped_ if it is not 
not referenced in a 
{xpack-ref}/mapping-roles.html#mapping-roles-file[role-mapping file]. API-based 
role mappings are not considered. Defaults to `false`.

`files.role_mapping`::
The {xpack-ref}/security-files.html[location] for the {xpack-ref}/mapping-roles.html#mapping-roles[
YAML role mapping configuration file]. Defaults to
`CONFIG_DIR/role_mapping.yml`.

`follow_referrals`::
Specifies whether {security} should follow referrals returned
by the LDAP server. Referrals are URLs returned by the server that are to be
used to continue the LDAP operation (for example, 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, which is used if the 
LDAP server requires client authentication. `ssl.key` and `ssl.keystore.path` 
cannot be used at the same time.

`ssl.key_passphrase`::
The passphrase that is used to decrypt the private key. This value is
optional as the key may not be encrypted.

`ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
The passphrase that is used to decrypt the private key.

`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.certificate_authorities` and `ssl.truststore.path` cannot be used at the 
same time.

`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.type`::
The format of the keystore file. Should be either `jks` to use the Java
Keystore format, or `PKCS12` to use PKCS#12 files. The default is `jks`.

`ssl.keystore.password`::
The password to the keystore.

`ssl.keystore.secure_password` (<<secure-settings,Secure>>)::
The password to the keystore.

`ssl.keystore.key_password`::
The password for the key in the keystore. Defaults to the keystore password.

`ssl.keystore.secure_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` cannot be used at the same time.

`ssl.truststore.password`::
The password to the truststore.

`ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
The password to the truststore.

`ssl.truststore.type`::
The format of the keystore file. Should be either `jks` to use the Java
Keystore format, or `PKCS12` to use PKCS#12 files. The default is `jks`.

`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`.
+
See <<ssl-tls-settings,`xpack.ssl.verification_mode`>> for an explanation of
these values.

`ssl.supported_protocols`::
Supported protocols for TLS/SSL (with versions). Defaults to the value of
`xpack.ssl.supported_protocols`.

`ssl.cipher_suites`:: Specifies the cipher suites that should be supported when 
communicating with the LDAP server. 
Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[
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 a hash of its 
credentials are cached for this period of time. Use the standard {es}
<<time-units,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 {xpack-ref}/controlling-user-cache.html#controlling-user-cache[Cache hash algorithms]
table for all possible values. Defaults to `ssha256`.

[[ref-ad-settings]]
[float]
===== Active Directory realm settings

The `type` setting must be set to `active_directory`. In addition to the 
<<ref-realm-settings,settings that are valid for all realms>>, you can specify  
the following settings: 

`url`::
An LDAP URL of the form `ldap[s]://<server>:<port>`. {security} attempts to 
authenticate against this URL. If the URL is not specified, it is derived from 
the `domain_name` setting and assumes an unencrypted connection to port 389. 
Defaults to `ldap://<domain_name>:389`. This setting is required when connecting 
using SSL/TLS or when using a custom port.

`load_balance.type`::
The behavior to use when there are multiple LDAP URLs defined. For supported
values see <<load-balancing,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. If the the `url` and `user_search_dn` 
settings are not specified, the cluster can derive those values from this 
setting. Required.

`bind_dn`::
The DN of the user that is used to bind to Active Directory and perform searches.
Defaults to Empty. Due to its potential security impact, `bind_dn` is not 
exposed via the <<cluster-nodes-info,nodes info API>>.

`bind_password`::
deprecated[6.3] Use `secure_bind_password` instead. The password for the user 
that is used to bind to Active Directory. Defaults to Empty. Due to its 
potential security impact, `bind_password` is not exposed via the 
<<cluster-nodes-info,nodes info API>>.

`secure_bind_password` (<<secure-settings,Secure>>)::
The password for the user that is used to bind to Active Directory.
Defaults to Empty.

`unmapped_groups_as_roles`::
If set to `true`, the names of any unmapped Active Directory groups are used as 
role names and assigned to the user. A group is considered _unmapped_ when it 
is not referenced in any role-mapping files. API-based role mappings are not 
considered. Defaults to `false`.

`files.role_mapping`::
The {xpack-ref}/security-files.html[location] for the YAML
role mapping configuration file. Defaults to `CONFIG_DIR/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`. If specified, this must be a valid LDAP user search filter. 
For example `(&(objectClass=user)(sAMAccountName={0}))`. For more information, 
see 
https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax].

`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. For more information, see 
https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax].

`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}))`. For more information, see 
https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax]. 

`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`. If the LDAP server is down, values greater than 0 
could cause startup failures. 

`user_search.pool.health_check.enabled`::
Enables or disables 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 that setting is present. Otherwise, it 
defaults to the value of the `user_search.base_dn` setting. 

`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.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.certificate_authorities` and `ssl.truststore.path` cannot be used at the 
same time.

`ssl.key`::
Path to the PEM encoded file containing the private key, which is used when the 
Active Directory server requires client authentication. `ssl.key` and 
`ssl.keystore.path` cannot be used at the same time.


`ssl.key_passphrase`::
The passphrase that is used to decrypt the private key. This value is
optional as the key might not be encrypted.

`ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
The passphrase that is used to decrypt the private key. This value is
optional as the key might not be encrypted.

`ssl.keystore.key_password`::
The password for the key in the keystore. Defaults to the keystore password.

`ssl.keystore.secure_key_password` (<<secure-settings,Secure>>)::
The password for the key in the keystore. Defaults to the keystore password.

`ssl.keystore.password`::
The password to the keystore.

`ssl.secure_keystore.password` (<<secure-settings,Secure>>)::
The password to the keystore.

`ssl.keystore.path`::
The path to the Java Keystore file that contains a private key and certificate.
`ssl.key` and `ssl.keystore.path` cannot be used at the same time.

`ssl.keystore.type`::
The format of the keystore file. Should be either `jks` to use the Java
Keystore format, or `PKCS12` to use PKCS#12 files. The default is `jks`.

`ssl.truststore.password`::
The password to the truststore.

`ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
The password to the truststore.

`ssl.truststore.path`::
The path to the Java Keystore file that contains the certificates to trust.
`ssl.certificate_authorities` and `ssl.truststore.path` cannot be used at the 
same time.

`ssl.truststore.type`::
The format of the truststore file. Should be either `jks` to use the Java
Keystore format, or `PKCS12` to use PKCS#12 files. The default is `jks`.

`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`.
+
See <<ssl-tls-settings,`xpack.ssl.verification_mode`>> for an explanation of
these values.

`ssl.supported_protocols`::
Supported protocols for TLS/SSL (with versions). Defaults to the value of
`xpack.ssl.supported_protocols`.

`ssl.cipher_suites`:: Specifies the cipher suites that should be supported when 
communicating with the Active Directory server. 
Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[
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 a hash of its 
credentials are cached for this configured period of time. Use the
standard Elasticsearch {ref}/common-options.html#time-units[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 {xpack-ref}/controlling-user-cache.html#controlling-user-cache[Cache hash algorithms] table for all possible values). Defaults to `ssha256`.

`follow_referrals`::
If set to `true` {security} follows referrals returned by the LDAP server. 
Referrals are URLs returned by the server that are to be used to continue the 
LDAP operation (such as `search`). Defaults to `true`.

[[ref-pki-settings]]
[float]
===== PKI realm settings

The `type` setting must be set to `pki`. In addition to the 
<<ref-realm-settings,settings that are valid for all realms>>, you can specify  
the following 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 paths to the PEM certificate files that should be used to authenticate a
user's certificate as trusted. Defaults to the trusted certificates configured
for SSL. This setting cannot be used with `truststore.path`. 

`truststore.algorithm`::
Algorithm for the truststore. Defaults to `SunX509`.

`truststore.password`::
The password for the truststore. Must be provided if `truststore.path` is set.

`truststore.secure_password` (<<secure-settings,Secure>>)::
The password for the truststore.

`truststore.path`::
The path of a truststore to use. Defaults to the trusted certificates configured
for SSL. This setting cannot be used with `certificate_authorities`.

`files.role_mapping`::
Specifies the {xpack-ref}/security-files.html[location] of the
{xpack-ref}/mapping-roles.html[YAML role  mapping configuration file].
Defaults to `CONFIG_DIR/role_mapping.yml`.

`cache.ttl`::
Specifies the time-to-live for cached user entries. A user and a hash of its 
credentials are cached for this period of time. Use the
standard {es} {ref}/common-options.html#time-units[time units]).
Defaults to `20m`.

`cache.max_users`::
Specifies the maximum number of user entries that the cache can contain.
Defaults to `100000`.

[[ref-saml-settings]]
[float]
===== SAML realm settings

The `type` setting must be set to `saml`. In addition to the 
<<ref-realm-settings,settings that are valid for all realms>>, you can specify  
the following settings: 

`idp.entity_id`::
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`::
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} automatically polls this metadata resource and reloads 
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`::
Controls the frequency with which `https` metadata is checked for changes.
Defaults to `1h` (1 hour).

`idp.use_single_logout`::
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`::
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 Kibana instance. For example, 
`https://kibana.example.com/`. 

`sp.acs`::
The URL of the Assertion Consumer Service within {kib}. Typically this is the 
"api/security/v1/saml" endpoint of your Kibana server. For example, 
`https://kibana.example.com/api/security/v1/saml`. 

`sp.logout`::
The URL of the Single Logout service within {kib}. Typically this is the 
"logout" endpoint of your Kibana server. For example, 
`https://kibana.example.com/logout`.

`attributes.principal`::
The Name of the SAML attribute that should be used as the {security} user's
principal (username).

`attributes.groups`::
The Name of the SAML attribute that should be used to populate {security}
user's groups. 

`attributes.name`::
The Name of the SAML attribute that should be used to populate {security}
user's full name. 

`attributes.mail`::
The Name of the SAML attribute that should be used to populate {security}
user's email address. 

`attributes.dn`::
The Name of the SAML attribute that should be used to populate {security}
user's X.500 _Distinguished Name_. 

`attribute_patterns.principal`::
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. For example, `^([^@]+)@example\\.com$` 
matches email addresses from the "example.com" domain and uses the local-part as 
the principal.

`attribute_patterns.groups`::
As per `attribute_patterns.principal`, but for the _group_ property.

`attribute_patterns.name`::
As per `attribute_patterns.principal`, but for the _name_ property.

`attribute_patterns.mail`::
As per `attribute_patterns.principal`, but for the _mail_ property.

`attribute_patterns.dn`::
As per `attribute_patterns.principal`, but for the _dn_ property.

`nameid_format`::
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`:: The value of the `AllowCreate` attribute of the 
`NameIdPolicy` element in an authentication request. Defaults to `false`. 

`nameid.sp_qualifier`:: 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`::
Specifies whether to set the `ForceAuthn` attribute when requesting that the IdP
authenticate the current user. If set to `true`, the IdP is required to verify 
the user’s identity, irrespective of any existing sessions they might have. 
Defaults to `false`.

`populate_user_metadata`::
Specifies whether to populate the {es} user's metadata with the values that are 
provided by the SAML attributes. Defaults to `true`.

`allowed_clock_skew`::
The maximum amount of skew that can be tolerated between the IdP's clock and the
{es} node's clock.
Defaults to `3m` (3 minutes).

[float]
[[ref-saml-signing-settings]]
===== SAML realm signing settings

If a signing key is configured (that is, either `signing.key` or 
`signing.keystore.path` is set), then {security} signs outgoing SAML messages. 
Signing can be configured using the following settings:

`signing.saml_messages`::
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`.
Only valid if `signing.key` or `signing.keystore.path` is also specified.
Defaults to `*`.

`signing.key`::
Specifies the path to the PEM encoded private key to use for SAML message signing.
`signing.key` and `signing.keystore.path` cannot be used at the same time.

`signing.secure_key_passphrase` (<<secure-settings,Secure>>)::
Specifies the passphrase to decrypt the PEM encoded private key (`signing.key`)
if it is encrypted.

`signing.certificate`::
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. This setting can only be used if `signing.key` is set.

`signing.keystore.path`::
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` cannot be used at the same time.

`signing.keystore.type`::
The type of the keystore in `signing.keystore.path`.
Must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", 
or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`.

`signing.keystore.alias`::
Specifies the alias of the key within the keystore that should be
used for SAML message signing. If the keystore contains more than one private 
key, this setting must be specified. 

`signing.keystore.secure_password` (<<secure-settings,Secure>>)::
The password to the keystore in `signing.keystore.path`.

`signing.keystore.secure_key_password` (<<secure-settings,Secure>>)::
The password for the key in the keystore (`signing.keystore.path`).
Defaults to the keystore password.

[float]
[[ref-saml-encryption-settings]]
===== SAML realm encryption settings

If an encryption key is configured (that is, either `encryption.key` or 
`encryption.keystore.path` is set), then {security} publishes an encryption 
certificate when generating metadata and attempts to decrypt incoming SAML 
content. Encryption can be configured using the following settings:

`encryption.key`::
Specifies the path to the PEM encoded private key to use for SAML message
decryption.
`encryption.key` and `encryption.keystore.path` cannot be used at the same time.

`encryption.secure_key_passphrase` (<<secure-settings,Secure>>)::
Specifies the passphrase to decrypt the PEM encoded private key
(`encryption.key`) if it is encrypted.

`encryption.certificate`::
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. This setting can be used only if `encryption.key` is set.

`encryption.keystore.path`::
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` cannot be used at the same time.

`encryption.keystore.type`::
The type of the keystore (`encryption.keystore.path`).
Must be either `jks` or `PKCS12`. If the keystore path ends in ".p12", ".pfx", 
or "pkcs12", this setting defaults to `PKCS12`. Otherwise, it defaults to `jks`.

`encryption.keystore.alias`::
Specifies the alias of the key within the keystore (`encryption.keystore.path`)
that should be used for SAML message decryption. If not specified, all compatible
key pairs from the keystore are considered as candidate keys for decryption.

`encryption.keystore.secure_password` (<<secure-settings,Secure>>)::
The password to the keystore (`encryption.keystore.path`).

`encryption.keystore.secure_key_password` (<<secure-settings,Secure>>)::
The password for the key in the keystore (`encryption.keystore.path`). Only a
single password is supported. If you are using multiple decryption keys, 
they cannot have individual passwords.

[float]
[[ref-saml-ssl-settings]]
===== 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), the following settings can be used to 
configure SSL. If these are not specified, then the 
<<ssl-tls-settings,default SSL settings>> are used.

NOTE: These settings are not used for any purpose other than loading metadata 
over https.

`ssl.key`::
Specifies the path to the PEM encoded private key to use for http client 
authentication (if required). `ssl.key` and `ssl.keystore.path` cannot be used 
at the same time.

`ssl.key_passphrase`::
Specifies the
passphrase to decrypt the PEM encoded private key (`ssl.key`) if it is
encrypted. Cannot be used with `ssl.secure_key_passphrase`. 

`ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
Specifies the
passphrase to decrypt the PEM encoded private key (`ssl.key`) if it is
encrypted. Cannot be used with `ssl.key_passphrase`. 

`ssl.certificate`::
Specifies the
path to the PEM encoded certificate (or certificate chain) that is associated
with the key (`ssl.key`). This setting can be used only if `ssl.key` is set.

`ssl.certificate_authorities`::
Specifies the
paths to the PEM encoded certificate authority certificates that should be
trusted. `ssl.certificate_authorities` and `ssl.truststore.path` cannot be
used at the same time.

`ssl.keystore.path`::
Specifies 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` cannot be used at the same time.

`ssl.keystore.type`::
The type of the keystore (`ssl.keystore.path`). Must be either `jks` or `PKCS12`.
If the keystore path ends in ".p12", ".pfx" or "pkcs12", this setting defaults 
to `PKCS12`. Otherwise, it defaults to `jks`.

`ssl.keystore.password`::
The password to the keystore (`ssl.keystore.path`). This setting cannot be used 
with `ssl.keystore.secure_password`.

`ssl.keystore.secure_password` (<<secure-settings,Secure>>)::
The password to the keystore (`ssl.keystore.path`).
This setting cannot be used with `ssl.keystore.password`.

`ssl.keystore.key_password`::
The password for the key in the keystore (`ssl.keystore.path`).
Defaults to the keystore password. This setting cannot be used with 
`ssl.keystore.secure_key_password`.

`ssl.keystore.secure_key_password` (<<secure-settings,Secure>>)::
The password for the key in the keystore (`ssl.keystore.path`).
Defaults to the keystore password. This setting cannot be used with 
`ssl.keystore.key_password`.

`ssl.truststore.path`::
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` cannot be used at the
same time.

`ssl.truststore.type`::
The type of the truststore (`ssl.truststore.path`). Must be either `jks` or 
`PKCS12`. If the keystore path ends in ".p12", ".pfx" or "pkcs12", this setting 
defaults to `PKCS12`. Otherwise, it defaults to `jks`.

`ssl.truststore.password`::
The password to the truststore (`ssl.truststore.path`). This setting cannot be 
used with `ssl.truststore.secure_password`.

`ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
The password to the truststore (`ssl.truststore.path`). This setting cannot be 
used with `ssl.truststore.password`.

`ssl.verification_mode`::
One of `full`
(verify the hostname and the certificate path), `certificate` (verify the
certificate path, but not the hostname) or `none` (perform no verification).
Defaults to `full`.
+
See <<ssl-tls-settings,`xpack.ssl.verification_mode`>> for a more detailed
explanation of these values.

`ssl.supported_protocols`::
Specifies the supported protocols for TLS/SSL.

`ssl.cipher_suites`::
Specifies the
cipher suites that should be supported.

[float]
[[load-balancing]]
===== Load balancing and failover

The `load_balance.type` setting can have the following values: 

* `failover`: The URLs specified are used in the order that they are specified. 
The first server that can be connected to will be used for all subsequent 
connections. If a connection to that server fails then the next server that a 
connection can be established to will be used for subsequent connections.
* `dns_failover`: In this mode of operation, only a single URL may be specified.
This URL must contain a DNS name. The system will be queried for all IP 
addresses that correspond to this DNS name. Connections to the Active Directory 
or LDAP server will always be tried in the order in which they were retrieved. 
This differs from `failover` in that there is no reordering of the list and if a 
server has failed at the beginning of the list, it will still be tried for each 
subsequent connection.
* `round_robin`: Connections will continuously iterate through the list of 
provided URLs. If a server is unavailable, iterating through the list of URLs 
will continue until a successful connection is made.
* `dns_round_robin`: In this mode of operation, only a single URL may be 
specified. This URL must contain a DNS name. The system will be queried for all 
IP addresses that correspond to this DNS name. Connections will continuously 
iterate through the list of addresses. If a server is unavailable, iterating 
through the list of URLs will continue until a successful connection is made.

[float]
[[ssl-tls-settings]]
==== Default TLS/SSL settings
You can configure the following TLS/SSL settings in
`elasticsearch.yml`. For more information, see
{xpack-ref}/encrypting-communications.html[Encrypting communications]. These settings will be used
for all of {xpack} 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`. This global setting is not applicable for HTTP, see
 <<http-tls-ssl-settings>>.

`xpack.ssl.verification_mode`::
Controls the verification of certificates. Valid values are:
- `full`, which verifies that the provided certificate is signed by a trusted
       authority (CA) and also verifies that the server's hostname (or IP
       address) matches the names identified within the certificate.
- `certificate`, which verifies that the provided certificate is signed by a
       trusted authority (CA), but does not perform any hostname verification.
- `none`, which performs _no verification_ of the server's certificate. This mode
       disables many of the security benefits of SSL/TLS and should only be
       used after very careful consideration. It is primarily intended as a
       temporary diagnostic mechanism when attempting to resolve TLS errors,
       and its use on production clusters is strongly discouraged.
+
The default value is `full`.

`xpack.ssl.cipher_suites`::
Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[
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`. If the _Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files_ has been installed, the default value also includes `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`,
`TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`,
`TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`.

[float]
[[tls-ssl-key-settings]]
===== 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 <<ssl-tls-settings, {xpack}
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 <<tls-ssl-key-settings, key settings>>. The key and certificate must be in place
for connections that require client authentication or when acting as a SSL enabled server.

[float]
===== 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 is used to decrypt the private key. This value is
optional as the key might not be encrypted.

`xpack.ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
The passphrase that is used to decrypt the private key. This value is
optional as the key might 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.

[float]
===== 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.secure_password` (<<secure-settings,Secure>>)::
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.keystore.secure_key_password` (<<secure-settings,Secure>>)::
Password for the private key in the keystore.

`xpack.ssl.truststore.path`::
Path to the truststore file.

`xpack.ssl.truststore.password`::
Password to the truststore.

`xpack.ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
Password to the truststore.

[float]
===== PKCS#12 files

When using PKCS#12 container files (`.p12` or `.pfx`), which contain the
private key, certificate, and certificates that should be trusted, use
the following settings:

`xpack.ssl.keystore.path`::
Path to the PKCS#12 file that holds the private key and certificate.

`xpack.ssl.keystore.type`::
Set this to `PKCS12`.

`xpack.ssl.keystore.password`::
Password to the PKCS#12 file.

`xpack.ssl.keystore.secure_password` (<<secure-settings,Secure>>)::
Password to the PKCS#12 file.

`xpack.ssl.keystore.key_password`::
Password for the private key in the PKCS12 file.
Defaults to the same value as `xpack.ssl.keystore.password`.

`xpack.ssl.keystore.secure_key_password` (<<secure-settings,Secure>>)::
Password for the private key in the PKCS12 file.

`xpack.ssl.truststore.path`::
Path to the truststore file.

`xpack.ssl.truststore.type`::
Set this to `PKCS12`.

`xpack.ssl.truststore.password`::
Password to the truststore.

`xpack.ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
Password to the truststore.

[[pkcs12-truststore-note]]
[NOTE]
Storing trusted certificates in a PKCS#12 file, although supported, is
uncommon in practice. The {ref}/certutil.html[`elasticsearch-certutil`] tool,
as well as Java's `keytool`, are designed to generate PKCS#12 files that
can be used both as a keystore and as a truststore, but this may not be the
case for container files that are created using other tools. Usually,
PKCS#12 files only contain secret and private entries. To confirm that
a PKCS#12 container includes trusted certificate ("anchor") entries look for
`2.16.840.1.113894.746875.1.1: <Unsupported tag 6>` in the
`openssl pkcs12 -info` output, or `trustedCertEntry` in the
`keytool -list` output.

[[http-tls-ssl-settings]]
:ssl-prefix:             xpack.security.http
:component:              HTTP
:client-auth-default:    none
:verifies!:
:server:

include::ssl-settings.asciidoc[]

[[transport-tls-ssl-settings]]
:ssl-prefix:             xpack.security.transport
:component:              Transport
:client-auth-default!:
:verifies:
:server:

include::ssl-settings.asciidoc[]

[[ssl-tls-profile-settings]]
[float]
===== Transport profile TLS/SSL settings
The same settings that are available for the <<transport-tls-ssl-settings, 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 key setting. For the default transport
this is `xpack.security.transport.ssl.key`. 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 key
setting, this would be `transport.profiles.$PROFILE.xpack.security.ssl.key`.

[[auditing-tls-ssl-settings]]
:ssl-prefix:             xpack.security.audit.index.client.xpack
:component:              Auditing
:client-auth-default!:
:server!:

include::ssl-settings.asciidoc[]

See also <<remote-audit-settings>>. 

[float]
[[ip-filtering-settings]]
==== IP filtering settings
You can configure the following settings for {xpack-ref}/ip-filtering.html[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.