Security settings in Elasticsearch
editSecurity settings in Elasticsearch
editYou configure xpack.security
settings to
enable anonymous access and perform message
authentication,
set up document and field level security,
configure realms,
encrypt communications with SSL,and
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 Elasticsearch keystore.
For more information about creating and updating the Elasticsearch keystore, see
Secure settings.
General security settings
edit-
xpack.security.enabled
-
(Static) Defaults to
true
, which enables Elasticsearch security features on the node.
If set to
false
, security features are disabled, which is not recommended. It also affects all Kibana instances that connect to this Elasticsearch instance; you do not need to disable security features in thosekibana.yml
files. For more information about disabling security features in specific Kibana instances, see Kibana security settings. -
xpack.security.autoconfiguration.enabled
-
(Static) Defaults to
true
, which enables security auto configuration.If set to
false
, security auto configuration is disabled, which is not recommended. When disabled, security is not configured automatically when starting Elasticsearch for the first time, which means that you must manually configure security. -
xpack.security.enrollment.enabled
-
(Static) Defaults to
false
. Controls enrollment (of nodes and Kibana) to a local node that’s been autoconfigured for security. When set totrue
, the local node can generate new enrollment tokens. Existing tokens can be used for enrollment if they are still valid.The security autoconfiguration process will set this to
true
unless an administrator sets it tofalse
before starting Elasticsearch. -
xpack.security.hide_settings
-
(Static)
A comma-separated list of settings that are omitted from the results of the
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 active_directory realm:
xpack.security.authc.realms.active_directory.ad1.*
. The API already omits allssl
settings,bind_dn
, andbind_password
due to the sensitive nature of the information. -
xpack.security.fips_mode.enabled
-
(Static)
Enables fips mode of operation. Set this to
true
if you run this Elasticsearch instance in a FIPS 140-2 enabled JVM. For more information, see FIPS 140-2. Defaults tofalse
.
Password hashing settings
edit-
xpack.security.authc.password_hashing.algorithm
-
(Static)
Specifies the hashing algorithm that is used for secure user credential storage.
See Table 2, “Password hashing algorithms”.
If
xpack.security.fips_mode.enabled
is true (see FIPS 140-2), defaults topbkdf2_stretch
. In all other cases, defaults tobcrypt
.
Anonymous access settings
editYou can configure the following anonymous access settings in
elasticsearch.yml
. For more information, see Enabling anonymous access.
-
xpack.security.authc.anonymous.username
-
(Static)
The username (principal) of the anonymous user. Defaults to
_es_anonymous_user
. -
xpack.security.authc.anonymous.roles
- (Static) The roles to associate with the anonymous user. Required.
-
xpack.security.authc.anonymous.authz_exception
-
(Static)
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 tofalse
, an HTTP 401 response is returned and the user can provide credentials with the appropriate permissions to gain access. Defaults totrue
.
Automata Settings
editIn places where the security features accept wildcard patterns (e.g. index patterns in roles, group matches in the role mapping API), each pattern is compiled into an Automaton. The follow settings are available to control this behaviour.
-
xpack.security.automata.max_determinized_states
-
(Static)
The upper limit on how many automaton states may be created by a single pattern.
This protects against too-difficult (e.g. exponentially hard) patterns.
Defaults to
100,000
. -
xpack.security.automata.cache.enabled
-
(Static)
Whether to cache the compiled automata. Compiling automata can be CPU intensive
and may slowdown some operations. The cache reduces the frequency with which
automata need to be compiled.
Defaults to
true
. -
xpack.security.automata.cache.size
-
(Static)
The maximum number of items to retain in the automata cache.
Defaults to
10,000
. -
xpack.security.automata.cache.ttl
-
(Static)
The length of time to retain in an item in the automata cache (based on most
recent usage).
Defaults to
48h
(48 hours).
Document and field level security settings
editYou can set the following document and field level security
settings in elasticsearch.yml
. For more information, see
Setting up field and document level security.
-
xpack.security.dls_fls.enabled
-
(Static)
Set to
false
to prevent document and field level security from being configured. Defaults totrue
. -
xpack.security.dls.bitset.cache.ttl
-
(Static)
The time-to-live for cached
BitSet
entries for document level security. Document level security queries may depend on Lucene BitSet objects, and these are automatically cached to improve performance. Defaults to expire entries that are unused for2h
(2 hours). -
xpack.security.dls.bitset.cache.size
-
(Static)
The maximum memory usage of cached
BitSet
entries for document level security. Document level security queries may depend on Lucene BitSet objects, and these are automatically cached to improve performance. Can be configured as a raw number of bytes (such as200mb
or1g
) or a percentage of the node’s JVM heap memory (such as5%
). When the default value is exceeded, the least recently used entries are evicted. Defaults to10%
of the heap assigned to the node.
Token service settings
editYou can set the following token service settings in
elasticsearch.yml
.
-
xpack.security.authc.token.enabled
-
(Static)
Set to
false
to disable the built-in token service. Defaults totrue
unlessxpack.security.http.ssl.enabled
isfalse
. This prevents sniffing the token from a connection over plain http. -
xpack.security.authc.token.timeout
-
(Static)
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.
API key service settings
editYou can set the following API key service settings in
elasticsearch.yml
.
-
xpack.security.authc.api_key.enabled
-
(Static)
Set to
false
to disable the built-in API key service. Defaults totrue
. -
xpack.security.authc.api_key.hashing.algorithm
-
(Static)
Specifies the hashing algorithm that is used for securing API key credentials.
See Table 2, “Password hashing algorithms”. Defaults to
pbkdf2
. -
xpack.security.authc.api_key.cache.ttl
-
(Static)
The time-to-live for cached API key entries. A API key id and a hash of its
API key are cached for this period of time. Specify the time period using
the standard Elasticsearch time units. Defaults to
1d
. -
xpack.security.authc.api_key.cache.max_keys
- (Static) The maximum number of API key entries that can live in the cache at any given time. Defaults to 10,000.
-
xpack.security.authc.api_key.cache.hash_algo
-
(Static, Expert)
The hashing algorithm that is used for the
in-memory cached API key credentials. For possible values, see Table 1, “Cache hash algorithms”.
Defaults to
ssha256
.
Security domain settings
editYou configure security domain settings in the xpack.security.authc.domains
namespace in elasticsearch.yml
.
For example:
Realm settings
editYou configure realm settings in the xpack.security.authc.realms
namespace in elasticsearch.yml
.
For example:
xpack.security.authc.realms: native.realm1: order: 0 ... ldap.realm2: order: 1 ... active_directory.realm3: order: 2 ... ...
Specifies the type of realm (for example, |
|
Specifies priority of a realm in the realm chain. This information is required. |
The valid settings vary depending on the realm type. For more information, see User authentication.
Settings valid for all realms
edit-
order
- (Static) The priority of the realm within the realm chain. Realms with a lower order are consulted first. The value must be unique for each realm. This setting is required.
-
enabled
-
(Static)
Indicates whether a realm is enabled. You can use this setting to disable a
realm without removing its configuration information. Defaults to
true
.
Native realm settings
editIn addition to the settings that are valid for all realms, you can specify the following optional settings:
-
cache.ttl
-
(Static)
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 Elasticsearch time units. Defaults to
20m
. -
cache.max_users
- (Static) The maximum number of user entries that can live in the cache at any given time. Defaults to 100,000.
-
cache.hash_algo
-
(Static, Expert)
The hashing algorithm that is used for the
in-memory cached user credentials. For possible values, see Table 1, “Cache hash algorithms”.
Defaults to
ssha256
. -
authentication.enabled
-
(Static)
If set to
false
, disables authentication support in this realm, so that it only supports user lookups. (See the run as and authorization realms features). Defaults totrue
.
File realm settings
editIn addition to the settings that are valid for all realms, you can specify the following settings:
-
cache.ttl
-
(Static)
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 Elasticsearch time units. Defaults to20m
. -
cache.max_users
- (Static) The maximum number of user entries that can live in the cache at a given time. Defaults to 100,000.
-
cache.hash_algo
-
(Static, Expert)
The hashing algorithm that is used for the in-memory cached
user credentials. See Table 1, “Cache hash algorithms”. Defaults to
ssha256
. -
authentication.enabled
-
(Static)
If set to
false
, disables authentication support in this realm, so that it only supports user lookups. (See the run as and authorization realms features). Defaults totrue
.
LDAP realm settings
editIn addition to the Settings valid for all realms, you can specify the following settings:
-
url
-
(Static) One or more LDAP URLs in the
ldap[s]://<server>:<port>
format. Required.To provide multiple URLs, use a YAML array (
["ldap://server1:636", "ldap://server2:636"]
) or comma-separated string ("ldap://server1:636, ldap://server2:636"
).While both are supported, you can’t mix the
ldap
andldaps
protocols. -
load_balance.type
-
(Static)
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
-
(Static)
When using
dns_failover
ordns_round_robin
as the load balancing type, this setting controls the amount of time to cache DNS lookups. Defaults to1h
. -
bind_dn
-
(Static)
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 nodes info API. -
bind_password
-
(Static)
[6.3]
Deprecated in 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 nodes info API. -
secure_bind_password
- (Secure) The password for the user that is used to bind to the LDAP directory. Defaults to Empty.
-
user_dn_templates
-
(Static)
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. Ifuser_search.base_dn
is specified, this setting is not valid. For more information on the different modes, see LDAP user authentication. -
authorization_realms
-
(Static) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the LDAP realm does not perform role mapping and instead loads the user from the listed realms. The referenced realms are consulted in the order that they are defined in this list. See Delegating authorization to another realm.
If any settings starting with
user_search
are specified, theuser_dn_templates
settings are ignored. -
user_group_attribute
-
(Static)
Specifies the attribute to examine on the user for group membership.
If any
group_search
settings are specified, this setting is ignored. Defaults tomemberOf
. -
user_search.base_dn
-
(Static)
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 LDAP user authentication. -
user_search.scope
-
(Static)
The scope of the user search. Valid values are
sub_tree
,one_level
orbase
.one_level
only searches objects directly contained within thebase_dn
.sub_tree
searches all objects contained underbase_dn
.base
specifies that thebase_dn
is the user object, and that it is the only user considered. Defaults tosub_tree
. -
user_search.filter
-
(Static)
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
-
(Static)
[5.6]
Deprecated in 5.6.
Use
user_search.filter
instead. The attribute to match with the username sent with the request. Defaults touid
. -
user_search.pool.enabled
-
(Static)
Enables or disables connection pooling for user search. If set to
false
, a new connection is created for every search. The default istrue
whenbind_dn
is set. -
user_search.pool.size
-
(Static)
The maximum number of connections to the LDAP server to allow in the
connection pool. Defaults to
20
. -
user_search.pool.initial_size
-
(Static)
The initial number of connections to create to the LDAP server on startup.
Defaults to
0
. If the LDAP server is down, values greater than0
could cause startup failures. -
user_search.pool.health_check.enabled
-
(Static)
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
-
(Static)
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 touser_search.base_dn
. -
user_search.pool.health_check.interval
-
(Static)
The interval to perform background checks of connections in the pool.
Defaults to
60s
. -
group_search.base_dn
-
(Static)
The container DN to search for groups in which the user has membership. When
this element is absent, Elasticsearch searches for the attribute specified by
user_group_attribute
set on the user in order to determine group membership. -
group_search.scope
-
(Static)
Specifies whether the group search should be
sub_tree
,one_level
orbase
.one_level
only searches objects directly contained within thebase_dn
.sub_tree
searches all objects contained underbase_dn
.base
specifies that thebase_dn
is a group object, and that it is the only group considered. Defaults tosub_tree
. -
group_search.filter
-
(Static)
Specifies a filter to use to look up a group.
When not set, the realm searches for
group
,groupOfNames
,groupOfUniqueNames
, orposixGroup
with the attributesmember
,memberOf
, ormemberUid
. Any instance of{0}
in the filter is replaced by the user attribute defined ingroup_search.user_attribute
. -
group_search.user_attribute
- (Static) 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
-
(Static)
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 referenced in a role-mapping file. API-based role mappings are not considered. Defaults tofalse
. -
files.role_mapping
-
(Static)
The location for the
YAML role mapping configuration file. Defaults to
ES_PATH_CONF/role_mapping.yml
. -
follow_referrals
-
(Static)
Specifies whether Elasticsearch 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
- (Static) 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
-
(Static)
The TCP connect timeout period for establishing an LDAP connection.
An
s
at the end indicates seconds, orms
indicates milliseconds. Defaults to5s
(5 seconds ). -
timeout.tcp_read
-
(Static)
[7.7]
Deprecated in 7.7.
The TCP read timeout period after establishing an LDAP
connection. This is equivalent to and is deprecated in favor of
timeout.response
and they cannot be used simultaneously. Ans
at the end indicates seconds, orms
indicates milliseconds. -
timeout.response
-
(Static)
The time interval to wait for the response from the LDAP server. An
s
at the end indicates seconds, orms
indicates milliseconds. Defaults to the value oftimeout.ldap_search
. -
timeout.ldap_search
-
(Static)
The timeout period for an LDAP search. The value is specified in the request
and is enforced by the receiving LDAP Server.
An
s
at the end indicates seconds, orms
indicates milliseconds. Defaults to5s
(5 seconds ). -
ssl.key
-
(Static) Path to a PEM encoded file containing the private key.
If HTTP client authentication is required, it uses this file. You cannot use this setting and
ssl.keystore.path
at the same time.If the LDAP server requires client authentication, it uses this file. You cannot use this setting and
ssl.keystore.path
at the same time. -
ssl.key_passphrase
-
(Static) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
You cannot use this setting and
ssl.secure_key_passphrase
at the same time. -
ssl.secure_key_passphrase
- (Secure) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
-
ssl.certificate
-
(Static) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key.
This setting can be used only if
ssl.key
is set.This certificate is presented to clients when they connect.
-
ssl.certificate_authorities
-
(Static) List of paths to PEM encoded certificate files that should be trusted.
This setting and
ssl.truststore.path
cannot be used at the same time.You cannot use this setting and
ssl.truststore.path
at the same time. -
ssl.keystore.path
-
(Static) The path for the keystore file that contains a private key and certificate.
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
ssl.key
at the same time.You cannot use this setting and
ssl.key
at the same time. -
ssl.keystore.type
-
(Static)
The format of the keystore file. It must be either
jks
orPKCS12
. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults toPKCS12
. Otherwise, it defaults tojks
. -
ssl.keystore.password
- (Static) The password for the keystore.
-
ssl.keystore.secure_password
- (Secure) The password for the keystore.
-
ssl.keystore.key_password
-
(Static) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.secure_password
at the same time. -
ssl.keystore.secure_key_password
- (Static) The password for the key in the keystore. The default is the keystore password.
-
ssl.truststore.path
-
(Static) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file.
You cannot use this setting and
ssl.certificate_authorities
at the same time.You cannot use this setting and
ssl.certificate_authorities
at the same time. -
ssl.truststore.password
-
(Static) The password for the truststore.
You cannot use this setting and
ssl.truststore.secure_password
at the same time. -
ssl.truststore.secure_password
- (Secure) Password for the truststore.
-
ssl.truststore.type
-
(Static)
The format of the truststore file. It must be either
jks
orPKCS12
. If the file name ends in ".p12", ".pfx" or "pkcs12", the default isPKCS12
. Otherwise, it defaults tojks
. -
ssl.verification_mode
-
(Static) Indicates the type of verification when using
ldaps
to protect against man in the middle attacks and certificate forgery.Valid values
-
full
-
Validates that the provided certificate: has an issue date that’s
within the
not_before
andnot_after
dates; chains to a trusted Certificate Authority (CA); has ahostname
or IP address that matches the names within the certificate. -
certificate
-
Validates the provided certificate and verifies that it’s signed by a
trusted authority (CA), but doesn’t check the certificate
hostname
. -
none
-
Performs no certificate validation.
Setting certificate validation to
none
disables many security benefits of SSL/TLS, which is very dangerous. Only set this value if instructed by Elastic Support as a temporary diagnostic mechanism when attempting to resolve TLS errors.
Defaults to
full
. -
-
ssl.supported_protocols
-
(Static) Supported protocols with versions. Valid protocols:
SSLv2Hello
,SSLv3
,TLSv1
,TLSv1.1
,TLSv1.2
,TLSv1.3
. If the JVM’s SSL provider supports TLSv1.3, the default isTLSv1.3,TLSv1.2,TLSv1.1
. Otherwise, the default isTLSv1.2,TLSv1.1
.Elasticsearch relies on your JDK’s implementation of SSL and TLS. View Supported SSL/TLS versions by JDK version for more information.
If
xpack.security.fips_mode.enabled
istrue
, you cannot useSSLv2Hello
orSSLv3
. See FIPS 140-2. -
ssl.cipher_suites
-
(Static) Specifies the cipher suites that should be supported when communicating with the LDAP server. Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is
TLS_AES_256_GCM_SHA384
,TLS_AES_128_GCM_SHA256
,TLS_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
,TLS_RSA_WITH_AES_256_GCM_SHA384
,TLS_RSA_WITH_AES_128_GCM_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA256
,TLS_RSA_WITH_AES_128_CBC_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA
,TLS_RSA_WITH_AES_128_CBC_SHA
.For more information, see Oracle’s Java Cryptography Architecture documentation.
-
cache.ttl
-
(Static)
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 Elasticsearch
time units. Defaults to
20m
. -
cache.max_users
-
(Static)
Specifies the maximum number of user entries that the cache can contain.
Defaults to
100000
. -
cache.hash_algo
-
(Static, Expert)
Specifies the hashing algorithm that is used for the
in-memory cached user credentials. See Table 1, “Cache hash algorithms”. Defaults to
ssha256
. -
authentication.enabled
-
(Static)
If set to
false
, disables authentication support in this realm, so that it only supports user lookups. (See the run as and authorization realms features). Defaults totrue
.
Active Directory realm settings
editIn addition to the settings that are valid for all realms, you can specify the following settings:
-
url
-
(Static) One or more LDAP URLs in the
ldap[s]://<server>:<port>
format. Defaults toldap://<domain_name>:389
. This setting is required when connecting using SSL/TLS or when using a custom port.To provide multiple URLs, use a YAML array (
["ldap://server1:636", "ldap://server2:636"]
) or comma-separated string ("ldap://server1:636, ldap://server2:636"
).While both are supported, you can’t mix the
ldap
andldaps
protocols.If no URL is provided, Elasticsearch uses a default of
ldap://<domain_name>:389
. This default uses thedomain_name
setting value and assumes an unencrypted connection to port 389. -
load_balance.type
-
(Static)
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
-
(Static)
When using
dns_failover
ordns_round_robin
as the load balancing type, this setting controls the amount of time to cache DNS lookups. Defaults to1h
. -
domain_name
-
(Static)
The domain name of Active Directory. If the
url
and theuser_search.base_dn
settings are not specified, the cluster can derive those values from this setting. Required. -
bind_dn
-
(Static)
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 nodes info API. -
bind_password
-
(Static)
[6.3]
Deprecated in 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 nodes info API. -
secure_bind_password
- (Secure) The password for the user that is used to bind to Active Directory. Defaults to Empty.
-
unmapped_groups_as_roles
-
(Static)
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 tofalse
. -
files.role_mapping
-
(Static)
The location for the YAML
role mapping configuration file. Defaults to
ES_PATH_CONF/role_mapping.yml
. -
user_search.base_dn
- (Static) The context to search for a user. Defaults to the root of the Active Directory domain.
-
user_search.scope
-
(Static)
Specifies whether the user search should be
sub_tree
,one_level
orbase
.one_level
only searches users directly contained within thebase_dn
.sub_tree
searches all objects contained underbase_dn
.base
specifies that thebase_dn
is a user object, and that it is the only user considered. Defaults tosub_tree
. -
user_search.filter
-
(Static)
Specifies a filter to use to lookup a user given a username. The default
filter looks up
user
objects with eithersAMAccountName
oruserPrincipalName
. If specified, this must be a valid LDAP user search filter. For example(&(objectClass=user)(sAMAccountName={0}))
. For more information, see Search Filter Syntax. -
user_search.upn_filter
-
(Static)
Specifies a filter to use to lookup a user given a user principal name.
The default filter looks up
user
objects with a matchinguserPrincipalName
. 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 Search Filter Syntax. -
user_search.down_level_filter
-
(Static)
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 matchingsAMAccountName
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 Search Filter Syntax. -
user_search.pool.enabled
-
(Static)
Enables or disables connection pooling for user search. When
disabled a new connection is created for every search. The
default is
true
whenbind_dn
is provided. -
user_search.pool.size
-
(Static)
The maximum number of connections to the Active Directory server to allow in the
connection pool. Defaults to
20
. -
user_search.pool.initial_size
-
(Static)
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
-
(Static)
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
-
(Static)
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 theuser_search.base_dn
setting. -
user_search.pool.health_check.interval
-
(Static)
The interval to perform background checks of connections in the pool.
Defaults to
60s
. -
group_search.base_dn
- (Static) The context to search for groups in which the user has membership. Defaults to the root of the Active Directory domain.
-
group_search.scope
-
(Static)
Specifies whether the group search should be
sub_tree
,one_level
orbase
.one_level
searches for groups directly contained within thebase_dn
.sub_tree
searches all objects contained underbase_dn
.base
specifies that thebase_dn
is a group object, and that it is the only group considered. Defaults tosub_tree
. -
metadata
- (Static) 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
-
(Static)
The TCP connect timeout period for establishing an LDAP connection.
An
s
at the end indicates seconds, orms
indicates milliseconds. Defaults to5s
(5 seconds ). -
timeout.tcp_read
-
(Static)
[7.7]
Deprecated in 7.7.
The TCP read timeout period after establishing an LDAP
connection. This is equivalent to and is deprecated in favor of
timeout.response
and they cannot be used simultaneously. Ans
at the end indicates seconds, orms
indicates milliseconds. Defaults to the value oftimeout.ldap_search
. -
timeout.response
-
(Static)
The time interval to wait for the response from the AD server. An
s
at the end indicates seconds, orms
indicates milliseconds. Defaults to the value oftimeout.ldap_search
. -
timeout.ldap_search
-
(Static)
The timeout period for an LDAP search. The value is specified in the request
and is enforced by the receiving LDAP Server.
An
s
at the end indicates seconds, orms
indicates milliseconds. Defaults to5s
(5 seconds ). -
ssl.certificate
-
(Static) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key.
This setting can be used only if
ssl.key
is set.This certificate is presented to clients when they connect.
-
ssl.certificate_authorities
-
(Static) List of paths to PEM encoded certificate files that should be trusted.
This setting and
ssl.truststore.path
cannot be used at the same time.You cannot use this setting and
ssl.truststore.path
at the same time. -
ssl.key
-
(Static) Path to a PEM encoded file containing the private key.
If HTTP client authentication is required, it uses this file. You cannot use this setting and
ssl.keystore.path
at the same time.If the Active Directory server requires client authentication, it uses this file. You cannot use this setting and
ssl.keystore.path
at the same time. -
ssl.key_passphrase
-
(Static) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
You cannot use this setting and
ssl.secure_key_passphrase
at the same time. -
ssl.secure_key_passphrase
- (Secure) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
-
ssl.keystore.key_password
-
(Static) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.secure_password
at the same time. -
ssl.keystore.secure_key_password
- (Secure) The password for the key in the keystore. The default is the keystore password.
-
ssl.keystore.password
- (Static) The password for the keystore.
-
ssl.secure_keystore.password
- (Secure) The password for the keystore.
-
ssl.keystore.path
-
(Static) The path for the keystore file that contains a private key and certificate.
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
ssl.key
at the same time.You cannot use this setting and
ssl.key
at the same time. -
ssl.keystore.type
-
(Static)
The format of the keystore file. It must be either
jks
orPKCS12
. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults toPKCS12
. Otherwise, it defaults tojks
. -
ssl.truststore.password
-
(Static) The password for the truststore.
You cannot use this setting and
ssl.truststore.secure_password
at the same time. -
ssl.truststore.secure_password
- (Secure) Password for the truststore.
-
ssl.truststore.path
-
(Static) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file.
You cannot use this setting and
ssl.certificate_authorities
at the same time.You cannot use this setting and
ssl.certificate_authorities
at the same time. -
ssl.truststore.type
-
(Static)
The format of the truststore file. It must be either
jks
orPKCS12
. If the file name ends in ".p12", ".pfx" or "pkcs12", the default isPKCS12
. Otherwise, it defaults tojks
. -
ssl.verification_mode
-
(Static) Indicates the type of verification when using
ldaps
to protect against man in the middle attacks and certificate forgery.Valid values
-
full
-
Validates that the provided certificate: has an issue date that’s
within the
not_before
andnot_after
dates; chains to a trusted Certificate Authority (CA); has ahostname
or IP address that matches the names within the certificate. -
certificate
-
Validates the provided certificate and verifies that it’s signed by a
trusted authority (CA), but doesn’t check the certificate
hostname
. -
none
-
Performs no certificate validation.
Setting certificate validation to
none
disables many security benefits of SSL/TLS, which is very dangerous. Only set this value if instructed by Elastic Support as a temporary diagnostic mechanism when attempting to resolve TLS errors.
Defaults to
full
. -
-
ssl.supported_protocols
-
(Static) Supported protocols with versions. Valid protocols:
SSLv2Hello
,SSLv3
,TLSv1
,TLSv1.1
,TLSv1.2
,TLSv1.3
. If the JVM’s SSL provider supports TLSv1.3, the default isTLSv1.3,TLSv1.2,TLSv1.1
. Otherwise, the default isTLSv1.2,TLSv1.1
.Elasticsearch relies on your JDK’s implementation of SSL and TLS. View Supported SSL/TLS versions by JDK version for more information.
If
xpack.security.fips_mode.enabled
istrue
, you cannot useSSLv2Hello
orSSLv3
. See FIPS 140-2. -
ssl.cipher_suites
-
(Static) Specifies the cipher suites that should be supported when communicating with the Active Directory server. Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is
TLS_AES_256_GCM_SHA384
,TLS_AES_128_GCM_SHA256
,TLS_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
,TLS_RSA_WITH_AES_256_GCM_SHA384
,TLS_RSA_WITH_AES_128_GCM_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA256
,TLS_RSA_WITH_AES_128_CBC_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA
,TLS_RSA_WITH_AES_128_CBC_SHA
.For more information, see Oracle’s Java Cryptography Architecture documentation.
-
cache.ttl
-
(Static)
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 time units).
Defaults to
20m
. -
cache.max_users
-
(Static)
Specifies the maximum number of user entries that the cache can contain.
Defaults to
100000
. -
cache.hash_algo
-
(Static, Expert)
Specifies the hashing algorithm that is used for
the in-memory cached user credentials. See Table 1, “Cache hash algorithms”. Defaults to
ssha256
. -
authentication.enabled
-
(Static)
If set to
false
, disables authentication support in this realm, so that it only supports user lookups. (See the run as and authorization realms features). Defaults totrue
. -
follow_referrals
-
(Static)
If set to
true
, Elasticsearch 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 assearch
). Defaults totrue
.
PKI realm settings
editIn addition to the settings that are valid for all realms, you can specify the following settings:
-
username_pattern
-
(Static)
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
-
(Static)
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
-
(Static)
Algorithm for the truststore. Defaults to
SunX509
. -
truststore.password
-
(Static) The password for the truststore.
You cannot use this setting and
ssl.truststore.secure_password
at the same time.
If truststore.path
is set, this setting is required.
-
truststore.secure_password
- (Secure) Password for the truststore.
-
truststore.path
-
(Static)
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
-
(Static)
Specifies the location of the
YAML role mapping configuration file.
Defaults to
ES_PATH_CONF/role_mapping.yml
. -
authorization_realms
- (Static) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the PKI realm does not perform role mapping and instead loads the user from the listed realms. See Delegating authorization to another realm.
-
cache.ttl
-
(Static)
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 Elasticsearch time units).
Defaults to
20m
. -
cache.max_users
-
(Static)
Specifies the maximum number of user entries that the cache can contain.
Defaults to
100000
. -
delegation.enabled
-
(Static)
Generally, in order for the clients to be authenticated by the PKI realm they
must connect directly to Elasticsearch. That is, they must not pass through proxies
which terminate the TLS connection. In order to allow for a trusted and
smart proxy, such as Kibana, to sit before Elasticsearch and terminate TLS
connections, but still allow clients to be authenticated on Elasticsearch by this realm,
you need to toggle this to
true
. Defaults tofalse
. If delegation is enabled, then eithertruststore.path
orcertificate_authorities
setting must be defined. For more details, see Configuring authentication delegation for PKI realms.
SAML realm settings
editIn addition to the settings that are valid for all realms, you can specify the following settings.
-
idp.entity_id
-
(Static)
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
-
(Static) 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 Elasticsearch config directory. If a URL is provided, then it must be either a
file
URL or ahttps
URL.Elasticsearch 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 Elasticsearch
resource.reload.interval.high
setting, which defaults to 5 seconds. HTTPS resources are polled at a frequency determined by the realm’sidp.metadata.http.refresh
andidp.metadata.http.minimum_refresh
settings.If the metadata resource is loaded from a file then the file must exist at node startup, if it does not exist then the node will fail to start. If the resource is loaded over HTTPS then (by default) the node will be tolerant of a failure to load the resource - the node will start and will continue to poll the URL for updates. The affected SAML realm will fail to authenticate users until the problem is resolved. To force the node to fail if the metadata is unavailable set
idp.metadata.http.fail_on_error
totrue
.
-
idp.metadata.http.fail_on_error
-
(Static)
If set to
true
, the realm will fail on startup (and prevent the node from starting) if it attempts to load metadata over HTTPS and that metadata is not available. If set tofalse
(the default), the node will start but the affected SAML realm will not support user authentication until the metadata can be successfully loaded. This setting is ignored if metadata is loaded from a file.
-
idp.metadata.http.refresh
-
(Static) Controls the frequency with which
https
metadata is checked for changes. Defaults to1h
(1 hour).Under some circumstances Elasticsearch may determine that the metadata needs to be checked more frequently. This may occur if previous attempts to load the metadata encountered an error, or if the metadata indicates that it is due to expire in less than the configured refresh interval. In these cases Elasticsearch will poll more often, but never more frequently than
idp.metadata.http.minimum_refresh
. If there is an attempt to authenticate against a realm that has not yet loaded metadata successfully, that realm may attempt to load metadata outside of the configured polling frequency.
-
idp.metadata.http.minimum_refresh
-
(Static)
Controls the minimum frequency with which
https
metadata is checked for changes. In regular operation Elasticsearch will use the value ofidp.metadata.http.refresh
as the polling interval. However, under some circumstances Elasticsearch may determine that it needs to poll more frequently. In these cases, theminimum_refresh
will set the minimum frequency at which the metdata will be checked. Defaults to5m
(5 minutes) and must not be set to a value greater thanidp.metadata.http.refresh
-
idp.use_single_logout
-
(Static)
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
-
(Static)
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
-
(Static)
The URL of the Assertion Consumer Service within Kibana. Typically this is the
"api/security/saml/callback" endpoint of your Kibana server. For example,
https://kibana.example.com/api/security/saml/callback
.
-
sp.logout
-
(Static)
The URL of the Single Logout service within Kibana. Typically this is the
"logout" endpoint of your Kibana server. For example,
https://kibana.example.com/logout
.
-
attributes.principal
- (Static) The Name of the SAML attribute that contains the user’s principal (username).
-
attributes.groups
- (Static) The Name of the SAML attribute that contains the user’s groups.
-
attributes.name
- (Static) The Name of the SAML attribute that contains the user’s full name.
-
attributes.mail
- (Static) The Name of the SAML attribute that contains the user’s email address.
-
attributes.dn
- (Static) The Name of the SAML attribute that contains the user’s X.50 Distinguished Name.
-
attribute_patterns.principal
-
(Static)
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
-
(Static)
As per
attribute_patterns.principal
, but for the group property.
-
attribute_patterns.name
-
(Static)
As per
attribute_patterns.principal
, but for the name property.
-
attribute_patterns.mail
-
(Static)
As per
attribute_patterns.principal
, but for the mail property.
-
attribute_patterns.dn
-
(Static)
As per
attribute_patterns.principal
, but for the dn property.
-
nameid_format
-
(Static)
The NameID format that should be requested when asking the IdP to authenticate
the current user. The default is to not include the
nameid_format
attribute.
-
nameid.allow_create
-
(Static)
The value of the
AllowCreate
attribute of theNameIdPolicy
element in an authentication request. The default value is false.
-
nameid.sp_qualifier
-
(Static)
The value of the
SPNameQualifier
attribute of theNameIdPolicy
element in an authentication request. The default is to not include theSPNameQualifier
attribute.
-
force_authn
-
(Static)
Specifies whether to set the
ForceAuthn
attribute when requesting that the IdP authenticate the current user. If set totrue
, the IdP is required to verify the user’s identity, irrespective of any existing sessions they might have. Defaults tofalse
.
-
populate_user_metadata
-
(Static)
Specifies whether to populate the Elasticsearch user’s metadata with the values that are
provided by the SAML attributes. Defaults to
true
. -
authorization_realms
- (Static) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the SAML realm does not perform role mapping and instead loads the user from the listed realms. See Delegating authorization to another realm.
-
allowed_clock_skew
-
(Static)
The maximum amount of skew that can be tolerated between the IdP’s clock and the
Elasticsearch node’s clock.
Defaults to
3m
(3 minutes).
-
req_authn_context_class_ref
-
(Static) A comma separated list of Authentication Context Class Reference values to be included in the Requested Authentication Context when requesting the IdP to authenticate the current user. The Authentication Context of the corresponding authentication response should contain at least one of the requested values.
For more information, see Requesting specific authentication methods.
SAML realm signing settings
editIf a signing key is configured (that is, either signing.key
or
signing.keystore.path
is set), then Elasticsearch signs outgoing SAML messages.
Signing can be configured using the following settings:
-
signing.saml_messages
-
(Static)
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 areAuthnRequest
,LogoutRequest
andLogoutResponse
. Only valid ifsigning.key
orsigning.keystore.path
is also specified. Defaults to*
.
-
signing.key
-
(Static)
Specifies the path to the PEM encoded private key to use for SAML message signing.
signing.key
andsigning.keystore.path
cannot be used at the same time. -
signing.secure_key_passphrase
-
(Secure)
Specifies the passphrase to decrypt the PEM encoded private key (
signing.key
) if it is encrypted.
-
signing.certificate
-
(Static)
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 ifsigning.key
is set.
-
signing.keystore.path
-
(Static)
The path to the keystore that contains a private key and certificate. It must be
either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
signing.key
at the same time.
-
signing.keystore.type
-
(Static)
The type of the keystore in
signing.keystore.path
. Must be eitherjks
orPKCS12
. If the keystore path ends in ".p12", ".pfx", or "pkcs12", this setting defaults toPKCS12
. Otherwise, it defaults tojks
.
-
signing.keystore.alias
- (Static) 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)
The password to the keystore in
signing.keystore.path
. -
signing.keystore.secure_key_password
-
(Secure)
The password for the key in the keystore (
signing.keystore.path
). Defaults to the keystore password.
SAML realm encryption settings
editIf an encryption key is configured (that is, either encryption.key
or
encryption.keystore.path
is set), then Elasticsearch publishes an encryption
certificate when generating metadata and attempts to decrypt incoming SAML
content. Encryption can be configured using the following settings:
-
encryption.key
-
(Static)
Specifies the path to the PEM encoded private key to use for SAML message
decryption.
encryption.key
andencryption.keystore.path
cannot be used at the same time. -
encryption.secure_key_passphrase
-
(Secure)
Specifies the passphrase to decrypt the PEM encoded private key
(
encryption.key
) if it is encrypted.
-
encryption.certificate
-
(Static)
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 ifencryption.key
is set.
-
encryption.keystore.path
-
(Static)
The path to the keystore that contains a private key and certificate. It must be
either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
encryption.key
at the same time.
-
encryption.keystore.type
-
(Static)
The type of the keystore (
encryption.keystore.path
). Must be eitherjks
orPKCS12
. If the keystore path ends in ".p12", ".pfx", or "pkcs12", this setting defaults toPKCS12
. Otherwise, it defaults tojks
.
-
encryption.keystore.alias
-
(Static)
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)
The password to the keystore (
encryption.keystore.path
). -
encryption.keystore.secure_key_password
-
(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.
SAML realm SSL settings
editIf 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.
These settings are not used for any purpose other than loading metadata over https.
-
ssl.key
-
(Static) Path to a PEM encoded file containing the private key.
If HTTP client authentication is required, it uses this file. You cannot use this setting and
ssl.keystore.path
at the same time.
-
ssl.key_passphrase
-
(Static) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
You cannot use this setting and
ssl.secure_key_passphrase
at the same time.
-
ssl.secure_key_passphrase
-
(Secure) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
You cannot use this setting and
ssl.key_passphrase
at the same time.
-
ssl.certificate
-
(Static) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key.
This setting can be used only if
ssl.key
is set.
-
ssl.certificate_authorities
-
(Static) List of paths to PEM encoded certificate files that should be trusted.
This setting and
ssl.truststore.path
cannot be used at the same time.
-
ssl.keystore.path
-
(Static) The path for the keystore file that contains a private key and certificate.
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
ssl.key
at the same time.
-
ssl.keystore.type
-
(Static)
The format of the keystore file. It must be either
jks
orPKCS12
. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults toPKCS12
. Otherwise, it defaults tojks
.
-
ssl.keystore.password
- (Static) The password for the keystore.
-
ssl.keystore.secure_password
-
(Secure) The password for the keystore.
You cannot use this setting and
ssl.keystore.password
at the same time. -
ssl.keystore.key_password
-
(Static) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.secure_password
at the same time.You cannot use this setting and
ssl.keystore.secure_key_password
at the same time. -
ssl.keystore.secure_key_password
- (Secure) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and ssl.keystore.key_password
at the same time.
-
ssl.truststore.path
-
(Static) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file.
You cannot use this setting and
ssl.certificate_authorities
at the same time.
-
ssl.truststore.type
-
(Static)
The format of the truststore file. It must be either
jks
orPKCS12
. If the file name ends in ".p12", ".pfx" or "pkcs12", the default isPKCS12
. Otherwise, it defaults tojks
.
-
ssl.truststore.password
-
(Static) The password for the truststore.
You cannot use this setting and
ssl.truststore.secure_password
at the same time.
-
ssl.truststore.secure_password
-
(Secure) Password for the truststore.
This setting cannot be used with
ssl.truststore.password
.
-
ssl.verification_mode
-
(Static) Controls the verification of certificates.
Valid values
-
full
-
Validates that the provided certificate: has an issue date that’s
within the
not_before
andnot_after
dates; chains to a trusted Certificate Authority (CA); has ahostname
or IP address that matches the names within the certificate. -
certificate
-
Validates the provided certificate and verifies that it’s signed by a
trusted authority (CA), but doesn’t check the certificate
hostname
. -
none
-
Performs no certificate validation.
Setting certificate validation to
none
disables many security benefits of SSL/TLS, which is very dangerous. Only set this value if instructed by Elastic Support as a temporary diagnostic mechanism when attempting to resolve TLS errors.
Defaults to
full
. -
-
ssl.supported_protocols
-
(Static) Supported protocols with versions. Valid protocols:
SSLv2Hello
,SSLv3
,TLSv1
,TLSv1.1
,TLSv1.2
,TLSv1.3
. If the JVM’s SSL provider supports TLSv1.3, the default isTLSv1.3,TLSv1.2,TLSv1.1
. Otherwise, the default isTLSv1.2,TLSv1.1
.Elasticsearch relies on your JDK’s implementation of SSL and TLS. View Supported SSL/TLS versions by JDK version for more information.
If
xpack.security.fips_mode.enabled
istrue
, you cannot useSSLv2Hello
orSSLv3
. See FIPS 140-2.
-
ssl.cipher_suites
-
(Static) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is
TLS_AES_256_GCM_SHA384
,TLS_AES_128_GCM_SHA256
,TLS_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
,TLS_RSA_WITH_AES_256_GCM_SHA384
,TLS_RSA_WITH_AES_128_GCM_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA256
,TLS_RSA_WITH_AES_128_CBC_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA
,TLS_RSA_WITH_AES_128_CBC_SHA
.For more information, see Oracle’s Java Cryptography Architecture documentation.
Kerberos realm settings
editIn addition to the settings that are valid for all realms, you can specify the following settings:
-
keytab.path
- (Static) Specifies the path to the Kerberos keytab file that contains the service principal used by this Elasticsearch node. This must be a location within the Elasticsearch configuration directory and the file must have read permissions. Required.
-
remove_realm_name
-
(Static)
Set to
true
to remove the realm part of principal names. Principal names in Kerberos have the formuser/instance@REALM
. If this option istrue
, the realm part (@REALM
) will not be included in the username. Defaults tofalse
. -
krb.debug
-
(Static)
Set to
true
to enable debug logs for the Java login module that provides support for Kerberos authentication. Defaults tofalse
.
-
cache.ttl
-
(Static)
The time-to-live for cached user entries. A user is cached for
this period of time. Specify the time period using the standard Elasticsearch
time units. Defaults to
20m
.
-
cache.max_users
- (Static) The maximum number of user entries that can live in the cache at any given time. Defaults to 100,000.
-
authorization_realms
- (Static) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the Kerberos realm does not perform role mapping and instead loads the user from the listed realms. See Delegating authorization to another realm.
OpenID Connect realm settings
editIn addition to the settings that are valid for all realms, you can specify the following settings.
-
op.issuer
- (Static) A verifiable Identifier for your OpenID Connect Provider. An Issuer Identifier is usually a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. The value for this setting should be provided by your OpenID Connect Provider.
-
op.authorization_endpoint
- (Static) The URL for the Authorization Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider.
-
op.token_endpoint
- (Static) The URL for the Token Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider.
-
op.userinfo_endpoint
- (Static) The URL for the User Info Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider.
-
op.endsession_endpoint
- (Static) The URL for the End Session Endpoint at the OpenID Connect Provider. The value for this setting should be provided by your OpenID Connect Provider.
-
op.jwkset_path
-
(Static) The path or URL to a JSON Web Key Set with the key material that the OpenID Connect Provider uses for signing tokens and claims responses. If a path is provided, then it is resolved relative to the Elasticsearch config directory. If a URL is provided, then it must be either a
file
URL or ahttps
URL. Elasticsearch automatically caches the retrieved JWK set to avoid unnecessary HTTP requests but will attempt to refresh the JWK upon signature verification failure, as this might indicate that the OpenID Connect Provider has rotated the signing keys.File-based resources are polled at a frequency determined by the global Elasticsearch
resource.reload.interval.high
setting, which defaults to 5 seconds. -
authorization_realms
- (Static) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the OpenID Connect realm does not perform role mapping and instead loads the user from the listed realms. See Delegating authorization to another realm.
-
rp.client_auth_method
-
(Static)
The client authentication method used by Elasticsearch to authenticate
to the OpenID Connect Provider. Can be
client_secret_basic
,client_secret_post
, orclient_secret_jwt
. Defaults toclient_secret_basic
.
-
rp.client_auth_jwt_signature_algorithm
-
(Static)
The signature algorithm that Elasticsearch uses to sign the JWT with which it authenticates
as a client to the OpenID Connect Provider when
client_secret_jwt
is selected forrp.client_auth_method
. Can be eitherHS256
,HS384
, orHS512
. Defaults toHS384
.
-
rp.redirect_uri
-
(Static)
The Redirect URI within Kibana. If you want to use the authorization code flow, this is the
api/security/oidc/callback
endpoint of your Kibana server. If you want to use the implicit flow, it is theapi/security/oidc/implicit
endpoint. For example,https://kibana.example.com/api/security/oidc/callback
.
-
rp.response_type
-
(Static)
OAuth 2.0 Response Type value that determines the authorization
processing flow to be used. Can be
code
for authorization code grant flow, or one ofid_token
,id_token token
for the implicit flow.
-
rp.signature_algorithm
-
(Static)
The signature algorithm that will be used by Elasticsearch in order to verify the
signature of the id tokens it will receive from the OpenID Connect Provider.
Allowed values are
HS256
,HS384
,HS512
,ES256
,ES384
,ES512
,RS256
,RS384
,RS512
,PS256
,PS384
,PS512
. Defaults toRS256
.
-
rp.requested_scopes
-
(Static)
The scope values that will be requested by the OpenID Connect Provider as
part of the Authentication Request. Optional, defaults to
openid
-
rp.post_logout_redirect_uri
- (Static) The Redirect URI (usually within Kibana) that the OpenID Connect Provider should redirect the browser to after a successful Single Logout.
-
claims.principal
- (Static) The name of the OpenID Connect claim that contains the user’s principal (username).
-
claims.groups
- (Static) The name of the OpenID Connect claim that contains the user’s groups.
-
claims.name
- (Static) The name of the OpenID Connect claim that contains the user’s full name.
-
claims.mail
- (Static) The name of the OpenID Connect claim that contains the user’s email address.
-
claims.dn
- (Static) The name of the OpenID Connect claim that contains the user’s X.509 Distinguished Name.
-
claim_patterns.principal
-
(Static)
A Java regular expression that is matched against the OpenID Connect claim specified
by
claims.principal
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.
-
claim_patterns.groups
-
(Static)
As per
claim_patterns.principal
, but for the group property.
-
claim_patterns.name
-
(Static)
As per
claim_patterns.principal
, but for the name property.
-
claim_patterns.mail
-
(Static)
As per
claim_patterns.principal
, but for the mail property.
-
claim_patterns.dn
-
(Static)
As per
claim_patterns.principal
, but for the dn property.
-
allowed_clock_skew
-
(Static)
The maximum allowed clock skew to be taken into consideration when validating
id tokens with regards to their creation and expiration times.
Defaults to
60s
.
-
populate_user_metadata
-
(Static)
Specifies whether to populate the Elasticsearch user’s metadata with the values that are
provided by the OpenID Connect claims. Defaults to
true
. -
http.proxy.host
-
(Static)
Specifies the address of the proxy server that will be used by the internal
http client for all back-channel communication to the OpenID Connect Provider
endpoints. This includes requests to the Token Endpoint, the Userinfo Endpoint
and requests to fetch the JSON Web Key Set from the OP if
op.jwkset_path
is set as a URL. -
http.proxy.scheme
-
(Static)
Specifies the protocol to use to connect to the proxy server that will be
used by the http client for all back-channel communication to the OpenID
Connect Provider endpoints. Defaults to
http
. Allowed values arehttp
orhttps
. -
http.proxy.port
-
(Static)
Specifies the port of the proxy server that will be used by the http
client for all backchannel communication to the OpenID Connect Provider
endpoints. Defaults to
80
.
-
http.connect_timeout
-
(Static)
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the timeout until a connection
is established. A value of zero means the timeout is not used. Defaults to
5s
.
-
http.connection_read_timeout
-
(Static)
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the timeout used when
requesting a connection from the connection manager. Defaults to
5s
-
http.socket_timeout
-
(Static)
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the socket timeout (SO_TIMEOUT)
in milliseconds, which is the timeout for waiting for data or, put differently,
a maximum period inactivity between two consecutive data packets). Defaults to
5s
.
-
http.max_connections
-
(Static)
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the maximum number of
connections allowed across all endpoints.
Defaults to
200
.
-
http.max_endpoint_connections
-
(Static)
Controls the behavior of the http client used for back-channel communication to
the OpenID Connect Provider endpoints. Specifies the maximum number of
connections allowed per endpoint.
Defaults to
200
.
-
http.tcp.keep_alive
-
(Static)
Whether to enable TCP keepalives on HTTP connections used for back-channel communication
to the OpenID Connect Provider endpoints. Defaults to
true
.
-
http.connection_pool_ttl
- (Static) Controls the behavior of the http client used for back-channel communication to the OpenID Connect Provider endpoints. Specifies the time-to-live of connections in the connection pool (default to 3 minutes). A connection is closed if it is idle for more than the specified timeout.
The server can also set the Keep-Alive
HTTP response header. The effective
time-to-live value is the smaller value between this setting and the Keep-Alive
reponse header. Configure this setting to -1
to let the server dictate the value.
If the header is not set by the server and the setting has value of -1
,
the time-to-live is infinite and connections never expire.
OpenID Connect realm SSL settings
editThe following settings can be used to configure SSL for all outgoing http connections to the OpenID Connect Provider endpoints.
These settings are only used for the back-channel communication between Elasticsearch and the OpenID Connect Provider
-
ssl.key
-
(Static) Path to a PEM encoded file containing the private key.
If HTTP client authentication is required, it uses this file. You cannot use this setting and
ssl.keystore.path
at the same time.
-
ssl.key_passphrase
-
(Static) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
You cannot use this setting and
ssl.secure_key_passphrase
at the same time.
-
ssl.secure_key_passphrase
-
(Secure) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
You cannot use this setting and
ssl.key_passphrase
at the same time.
-
ssl.certificate
-
(Static) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key.
This setting can be used only if
ssl.key
is set.
-
ssl.certificate_authorities
-
(Static) List of paths to PEM encoded certificate files that should be trusted.
This setting and
ssl.truststore.path
cannot be used at the same time.
-
ssl.keystore.path
-
(Static) The path for the keystore file that contains a private key and certificate.
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
ssl.key
at the same time.
-
ssl.keystore.type
-
(Static)
The format of the keystore file. It must be either
jks
orPKCS12
. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults toPKCS12
. Otherwise, it defaults tojks
.
-
ssl.keystore.password
- (Static) The password for the keystore.
-
ssl.keystore.secure_password
-
(Secure) The password for the keystore.
You cannot use this setting and
ssl.keystore.password
at the same time. -
ssl.keystore.key_password
-
(Static) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.secure_password
at the same time.You cannot use this setting and
ssl.keystore.secure_key_password
at the same time. -
ssl.keystore.secure_key_password
-
(Secure) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.key_password
at the same time.
-
ssl.truststore.path
-
(Static) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file.
You cannot use this setting and
ssl.certificate_authorities
at the same time.
-
ssl.truststore.type
-
(Static)
The format of the truststore file. It must be either
jks
orPKCS12
. If the file name ends in ".p12", ".pfx" or "pkcs12", the default isPKCS12
. Otherwise, it defaults tojks
.
-
ssl.truststore.password
-
(Static) The password for the truststore.
You cannot use this setting and
ssl.truststore.secure_password
at the same time.
-
ssl.truststore.secure_password
-
(Secure) Password for the truststore.
You cannot use this setting and
ssl.truststore.password
at the same time.
-
ssl.verification_mode
-
(Static) Controls the verification of certificates.
Valid values
-
full
-
Validates that the provided certificate: has an issue date that’s
within the
not_before
andnot_after
dates; chains to a trusted Certificate Authority (CA); has ahostname
or IP address that matches the names within the certificate. -
certificate
-
Validates the provided certificate and verifies that it’s signed by a
trusted authority (CA), but doesn’t check the certificate
hostname
. -
none
-
Performs no certificate validation.
Setting certificate validation to
none
disables many security benefits of SSL/TLS, which is very dangerous. Only set this value if instructed by Elastic Support as a temporary diagnostic mechanism when attempting to resolve TLS errors.
Defaults to
full
. -
-
ssl.supported_protocols
-
(Static) Supported protocols with versions. Valid protocols:
SSLv2Hello
,SSLv3
,TLSv1
,TLSv1.1
,TLSv1.2
,TLSv1.3
. If the JVM’s SSL provider supports TLSv1.3, the default isTLSv1.3,TLSv1.2,TLSv1.1
. Otherwise, the default isTLSv1.2,TLSv1.1
.Elasticsearch relies on your JDK’s implementation of SSL and TLS. View Supported SSL/TLS versions by JDK version for more information.
If
xpack.security.fips_mode.enabled
istrue
, you cannot useSSLv2Hello
orSSLv3
. See FIPS 140-2.
-
ssl.cipher_suites
-
(Static) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is
TLS_AES_256_GCM_SHA384
,TLS_AES_128_GCM_SHA256
,TLS_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
,TLS_RSA_WITH_AES_256_GCM_SHA384
,TLS_RSA_WITH_AES_128_GCM_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA256
,TLS_RSA_WITH_AES_128_CBC_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA
,TLS_RSA_WITH_AES_128_CBC_SHA
.For more information, see Oracle’s Java Cryptography Architecture documentation.
JWT realm settings
editIn addition to the settings that are valid for all realms, you can specify the following settings.
-
token_type
-
(Static)
The token type,
id_token
oraccess_token
, that the JWT realm uses to verify incoming JWTs. Defaults toid_token
.
-
allowed_audiences
-
(Static)
A list of allowed JWT audiences that Elasticsearch should verify. Elasticsearch will only consume
JWTs that were intended for any of these audiences, as denoted by the
aud
claim in the JWT). The audiences are compared with exact string matches and do not support wildcards or regex. Examples ofaud
claim arehttps://example.com/client1
andother_service,elasticsearch
. Whentoken_type
isaccess_token
, the audiences can be optionally denoted by a different claim in the JWT ifaud
does not exist. See alsofallback_claims.aud
.
-
allowed_clock_skew
- (Static) The maximum allowed clock skew to be taken into consideration when validating JWTs with regards to their creation, not before, and expiration times.
-
allowed_issuer
-
(Static)
A verifiable Identifier for your JWT Issuer. An Issuer
Identifier is usually a case sensitive URL using the https scheme that contains
scheme, host, and optionally, port number and path components and no query or
fragment components. However, it can be any string. The value for this setting
should be provided by your JWT Issuer.
The issuer is compared with exact string matches and do not support wildcards or regex.
Examples of
iss
claim arehttps://example.com:8443/jwt
andissuer123
.
-
allowed_subjects
-
(Static)
A list of allowed JWT subjects that Elasticsearch should verify. Elasticsearch will only consume
JWTs that were issued for any of these subjects, as denoted by the
sub
claim in the JWT. The subjects are compared with exact string matches and do not support wildcards or regex. Examples ofsub
claim arehttps://example.com/user1
anduser_1,user2
. Whentoken_type
isaccess_token
, this setting is mandatory and the subject can be optionally denoted by a different claim in the JWT ifsub
does not exist. See alsofallback_claims.sub
.
-
fallback_claims.sub
-
(Static)
The alternative claim to look for the subject information if the
sub
claim does not exist. It is configurable only when thetoken_type
isaccess_token
. The fallback is applied everywhere thesub
claim is used.
-
fallback_claims.aud
-
(Static)
The alternative claim to look for the audiences information if the
aud
claim does not exist. It is configurable only when thetoken_type
isaccess_token
. The fallback is applied everywhere theaud
claim is used.
-
required_claims
- (Static) Additional claims and associated values that Elasticsearch should verify. This is a group setting that takes key/value pairs, where the key is a string and the value must be either a string or an array of strings. The values are compared with exact string matches and do not support wildcards or regex.
For example:
xpack.security.authc.realms.jwt.jwt1: required_claims: token_use: "id" versions: ["1.0", "2.0"]
-
allowed_signature_algorithms
-
(Static)
A list of signature algorithms that will be used by Elasticsearch in order to verify the
signature of the JWT it will receive from the JWT Issuer.
Defaults to
RS256
. Examples areHS512,RS512,ES512
andES384
. Allowed values areHS256
,HS384
,HS512
,ES256
,ES384
,ES512
,RS256
,RS384
,RS512
,PS256
,PS384
,PS512
. -
authorization_realms
- (Static) The names of the realms that should be consulted for delegated authorization. If this setting is used, then the JWT realm does not perform role mapping and instead loads the user from the listed realms. See Delegating authorization to another realm.
-
claims.dn
- (Static) The name of the JWT claim that contains the user’s Distinguished Name (DN), which uniquely identifies a user or group.
-
claim_patterns.dn
-
(Static)
Accepts the same Java regular expression as
claim_patterns.principal
, but for thedn
property.
-
claims.groups
-
(Static)
The name of the JWT claim that contains the user’s groups, such as
groups
androles
.
-
claim_patterns.group
-
(Static)
Accepts the same Java regular expression as
claim_patterns.principal
, but for thegroup
property.
-
claims.mail
- (Static) The name of the JWT claim that contains the user’s e-mail address.
-
claim_patterns.mail
-
(Static)
Accepts the same Java regular expression as
claim_patterns.principal
, but for themail
property.
-
claims.name
- (Static) The name of the JWT claim that contains the user’s username.
-
claim_patterns.name
-
(Static)
Accepts the same Java regular expression as
claim_patterns.principal
, but for thename
property.
-
claims.principal
-
(Static)
The name of the JWT claim that contains the user’s principal (username), such as
sub
,name
,email
, anddn
.
-
claim_patterns.principal
-
(Static)
An optional Java regular expression that is matched against the JWT claim specified
by
claims.principal
before it is applied to the user’sprincipal
property. The 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 theexample.com
domain and uses the local-part as the principal. Another example issub
which may not need a pattern setting.
-
client_authentication.type
-
(Static) Specifies whether to use
shared_secret
ornone
to authenticate incoming client requests. If this value isshared_secret
, the client is authenticated using an HTTP request header that must match a pre-configured secret value. The client must provide this shared secret with every request in theES-Client-Authentication
header. If this value isnone
, then the request headerES-Client-Authentication
is ignored. Defaults toshared_secret
.Enabling client authentication is recommended. If JWT bearer tokens are shared with other clients or services, client authentication restricts which ones are allowed to submit those JWTs to Elasticsearch.
-
client_authentication.shared_secret
-
(Secure)
Secret value string for client authentication.
Required if
client_authentication.type
isshared_secret
.
-
http.connect_timeout
-
(Static)
Sets the timeout for the HTTP client that is used for fetching the JSON Web Key
Set from a remote URL. A value of zero means the timeout is not used. Defaults
to
5s
.
-
http.connection_read_timeout
-
(Static)
Specifies the HTTP timeout used when requesting a connection from the connection
manager. Defaults to
5s
.
-
http.socket_timeout
-
(Static)
Specifies the maximum socket timeout (SO_TIMEOUT) for the HTTP client to wait
for inactivity between two consecutive data packets. Defaults to
5s
.
-
http.max_connections
- (Static) Specifies the maximum number of connections allowed across all endpoints.
-
http.max_endpoint_connections
- (Static) Specifies the maximum number of connections allowed per endpoint.
-
jwt.cache.size
-
(Static)
Specifies the maximum number of JWT cache entries. If clients use a different
JWT for every request, set to
0
to disable the JWT cache. Defaults to100000
. -
jwt.cache.ttl
-
(Static)
Specifies the time-to-live for the period of time to cache JWT entries.
JWTs can only be cached if client authentication is successful (or disabled).
Uses the standard Elasticsearch time units. If clients use a different JWT
for every request, set to
0
to disable the JWT cache. Defaults to20m
.
-
pkc_jwkset_path
-
(Static) The file path or URL to a JSON Web Key Set (JWKS) with the public key material that the JWT Realm uses for verifying token signatures. If a path is provided, then it is resolved relative to the Elasticsearch configuration directory. In Elastic Cloud, use an absolute path starting with
/app/config/
.If a URL is provided, then it must be either a
file
URL or anhttps
URL. Elasticsearch automatically caches the retrieved JWK set to avoid unnecessary HTTP requests, but will attempt to refresh the JWK upon signature verification failure, as this might indicate that the JWT Provider has rotated the signing keys.File-based resources are polled at a frequency determined by the global Elasticsearch
resource.reload.interval.high
setting, which defaults to5s
.
-
hmac_jwkset
-
(Secure)
Contents of a JSON Web Key Set (JWKS), including the secret key that the JWT
realm uses to verify token signatures. This format supports multiple keys and
optional attributes, and is preferred over the
hmac_key
setting. Cannot be used in conjunction with thehmac_key
setting. Refer to Configure Elasticsearch to use a JWT realm.
-
hmac_key
-
(Secure)
Contents of a single JSON Web Key (JWK), including the secret key that the JWT
realm uses to verify token signatures. This format only supports a single key
without attributes, and cannot be used with the
hmac_jwkset
setting. This format is compatible with OIDC. The HMAC key must be a UNICODE string, where the key bytes are the UTF-8 encoding of the UNICODE string. Thehmac_jwkset
setting is preferred. Refer to Configure Elasticsearch to use a JWT realm.
-
populate_user_metadata
-
(Static)
Specifies whether to populate the Elasticsearch user’s metadata with the values that are
provided by the JWT claims. Defaults to
true
.
JWT realm SSL settings
editThe following settings can be used to configure SSL for fetching the JSON Web Key Set from a remote URL.
These settings are only used for the back-channel communication between Elasticsearch and the JWT Issuer.
-
ssl.key
-
(Static) Path to a PEM encoded file containing the private key.
If HTTP client authentication is required, it uses this file. You cannot use this setting and
ssl.keystore.path
at the same time.
-
ssl.key_passphrase
-
(Static) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
You cannot use this setting and
ssl.secure_key_passphrase
at the same time.
-
ssl.secure_key_passphrase
-
(Secure) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
You cannot use this setting and
ssl.key_passphrase
at the same time.
-
ssl.certificate
-
(Static) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key.
This setting can be used only if
ssl.key
is set.
-
ssl.certificate_authorities
-
(Static) List of paths to PEM encoded certificate files that should be trusted.
This setting and
ssl.truststore.path
cannot be used at the same time.
-
ssl.keystore.path
-
(Static) The path for the keystore file that contains a private key and certificate.
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
ssl.key
at the same time.
-
ssl.keystore.type
-
(Static)
The format of the keystore file. It must be either
jks
orPKCS12
. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults toPKCS12
. Otherwise, it defaults tojks
.
-
ssl.keystore.secure_password
-
(Secure) The password for the keystore.
You cannot use this setting and
ssl.keystore.password
at the same time. -
ssl.keystore.key_password
-
(Static) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.secure_password
at the same time.You cannot use this setting and
ssl.keystore.secure_key_password
at the same time. -
ssl.keystore.secure_key_password
-
(Secure) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.key_password
at the same time.
-
ssl.truststore.path
-
(Static) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file.
You cannot use this setting and
ssl.certificate_authorities
at the same time.
-
ssl.truststore.type
-
(Static)
The format of the truststore file. It must be either
jks
orPKCS12
. If the file name ends in ".p12", ".pfx" or "pkcs12", the default isPKCS12
. Otherwise, it defaults tojks
.
-
ssl.truststore.password
-
(Static) The password for the truststore.
You cannot use this setting and
ssl.truststore.secure_password
at the same time.
-
ssl.truststore.secure_password
-
(Secure) Password for the truststore.
You cannot use this setting and
ssl.truststore.password
at the same time.
-
ssl.verification_mode
-
(Static) Controls the verification of certificates.
Valid values
-
full
-
Validates that the provided certificate: has an issue date that’s
within the
not_before
andnot_after
dates; chains to a trusted Certificate Authority (CA); has ahostname
or IP address that matches the names within the certificate. -
certificate
-
Validates the provided certificate and verifies that it’s signed by a
trusted authority (CA), but doesn’t check the certificate
hostname
. -
none
-
Performs no certificate validation.
Setting certificate validation to
none
disables many security benefits of SSL/TLS, which is very dangerous. Only set this value if instructed by Elastic Support as a temporary diagnostic mechanism when attempting to resolve TLS errors.
Defaults to
full
. -
-
ssl.supported_protocols
-
(Static) Supported protocols with versions. Valid protocols:
SSLv2Hello
,SSLv3
,TLSv1
,TLSv1.1
,TLSv1.2
,TLSv1.3
. If the JVM’s SSL provider supports TLSv1.3, the default isTLSv1.3,TLSv1.2,TLSv1.1
. Otherwise, the default isTLSv1.2,TLSv1.1
.Elasticsearch relies on your JDK’s implementation of SSL and TLS. View Supported SSL/TLS versions by JDK version for more information.
If
xpack.security.fips_mode.enabled
istrue
, you cannot useSSLv2Hello
orSSLv3
. See FIPS 140-2.
-
ssl.cipher_suites
-
(Static) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is
TLS_AES_256_GCM_SHA384
,TLS_AES_128_GCM_SHA256
,TLS_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
,TLS_RSA_WITH_AES_256_GCM_SHA384
,TLS_RSA_WITH_AES_128_GCM_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA256
,TLS_RSA_WITH_AES_128_CBC_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA
,TLS_RSA_WITH_AES_128_CBC_SHA
.For more information, see Oracle’s Java Cryptography Architecture documentation.
Load balancing and failover
editThe static 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 fromfailover
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.
General TLS settings
edit-
xpack.security.ssl.diagnose.trust
-
(Static)
Controls whether to output diagnostic messages for SSL/TLS trust failures.
If this is
true
(the default), a message will be printed to the Elasticsearch log whenever an SSL connection (incoming or outgoing) is rejected due to a failure to establish trust. This diagnostic message contains information that can be used to determine the cause of the failure and assist with resolving the problem. Set tofalse
to disable these messages.
TLS/SSL key and trusted certificate settings
editThe 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 no trusted certificates are configured, the default certificates that are trusted by the JVM will be trusted along with the certificate(s) associated with a key in the same context. The key and certificate must be in place for connections that require client authentication or when acting as a SSL enabled server.
Storing trusted certificates in a PKCS#12 file, although supported, is
uncommon in practice. The 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
editYou can configure the following TLS/SSL settings.
-
xpack.security.http.ssl.enabled
-
(Static)
Used to enable or disable TLS/SSL on the HTTP networking layer, which Elasticsearch uses to communicate with other clients. The default is
false
. -
xpack.security.http.ssl.supported_protocols
-
(Static) Supported protocols with versions. Valid protocols:
SSLv2Hello
,SSLv3
,TLSv1
,TLSv1.1
,TLSv1.2
,TLSv1.3
. If the JVM’s SSL provider supports TLSv1.3, the default isTLSv1.3,TLSv1.2,TLSv1.1
. Otherwise, the default isTLSv1.2,TLSv1.1
.Elasticsearch relies on your JDK’s implementation of SSL and TLS. View Supported SSL/TLS versions by JDK version for more information.
If
xpack.security.fips_mode.enabled
istrue
, you cannot useSSLv2Hello
orSSLv3
. See FIPS 140-2. -
xpack.security.http.ssl.client_authentication
-
(Static)
Controls the server’s behavior in regard to requesting a certificate
from client connections. Valid values are
required
,optional
, andnone
.required
forces a client to present a certificate, whileoptional
requests a client certificate but the client is not required to present one. Defaults tonone
. -
xpack.security.http.ssl.verification_mode
-
(Static) The SSL settings in
xpack.security.http.ssl
control a server context for TLS, which defines the settings for the TLS connection. The use ofverification_mode
in a TLS server is discouraged. Defines how to verify the certificates presented by another party in the TLS connection:Valid values
-
full
-
Validates that the provided certificate: has an issue date that’s
within the
not_before
andnot_after
dates; chains to a trusted Certificate Authority (CA); has ahostname
or IP address that matches the names within the certificate. -
certificate
-
Validates the provided certificate and verifies that it’s signed by a
trusted authority (CA), but doesn’t check the certificate
hostname
. -
none
-
Performs no certificate validation.
Setting certificate validation to
none
disables many security benefits of SSL/TLS, which is very dangerous. Only set this value if instructed by Elastic Support as a temporary diagnostic mechanism when attempting to resolve TLS errors.
Defaults to
full
. -
-
xpack.security.http.ssl.cipher_suites
-
(Static) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is
TLS_AES_256_GCM_SHA384
,TLS_AES_128_GCM_SHA256
,TLS_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
,TLS_RSA_WITH_AES_256_GCM_SHA384
,TLS_RSA_WITH_AES_128_GCM_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA256
,TLS_RSA_WITH_AES_128_CBC_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA
,TLS_RSA_WITH_AES_128_CBC_SHA
.For more information, see Oracle’s Java Cryptography Architecture documentation.
HTTP TLS/SSL key and trusted certificate settings
editThe 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. A private key and certificate must be configured.
PEM encoded files
editWhen using PEM encoded files, use the following settings:
-
xpack.security.http.ssl.key
-
(Static) Path to a PEM encoded file containing the private key.
If HTTP client authentication is required, it uses this file. You cannot use this setting and
ssl.keystore.path
at the same time. -
xpack.security.http.ssl.key_passphrase
-
(Static) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
You cannot use this setting and
ssl.secure_key_passphrase
at the same time. -
xpack.security.http.ssl.secure_key_passphrase
- (Secure) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
-
xpack.security.http.ssl.certificate
-
(Static) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key.
This setting can be used only if
ssl.key
is set. -
xpack.security.http.ssl.certificate_authorities
-
(Static) List of paths to PEM encoded certificate files that should be trusted.
This setting and
ssl.truststore.path
cannot be used at the same time.
Java keystore files
editWhen 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
-
(Static) The path for the keystore file that contains a private key and certificate.
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
ssl.key
at the same time. -
xpack.security.http.ssl.keystore.password
- (Static) The password for the keystore.
-
xpack.security.http.ssl.keystore.secure_password
- (Secure) The password for the keystore.
-
xpack.security.http.ssl.keystore.key_password
-
(Static) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.secure_password
at the same time. -
xpack.security.http.ssl.keystore.secure_key_password
- (Secure) The password for the key in the keystore. The default is the keystore password.
-
xpack.security.http.ssl.truststore.path
-
(Static) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file.
You cannot use this setting and
ssl.certificate_authorities
at the same time. -
xpack.security.http.ssl.truststore.password
-
(Static) The password for the truststore.
You cannot use this setting and
ssl.truststore.secure_password
at the same time. -
xpack.security.http.ssl.truststore.secure_password
- (Secure) Password for the truststore.
PKCS#12 files
editElasticsearch can be configured to use PKCS#12 container files (.p12
or .pfx
files)
that contain the private key, certificate and certificates that should be trusted.
PKCS#12 files are configured in the same way as Java keystore files:
-
xpack.security.http.ssl.keystore.path
-
(Static) The path for the keystore file that contains a private key and certificate.
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
ssl.key
at the same time. -
xpack.security.http.ssl.keystore.type
-
(Static)
The format of the keystore file. It must be either
jks
orPKCS12
. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults toPKCS12
. Otherwise, it defaults tojks
. -
xpack.security.http.ssl.keystore.password
- (Static) The password for the keystore.
-
xpack.security.http.ssl.keystore.secure_password
- (Secure) The password for the keystore.
-
xpack.security.http.ssl.keystore.key_password
-
(Static) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.secure_password
at the same time. -
xpack.security.http.ssl.keystore.secure_key_password
- (Secure) The password for the key in the keystore. The default is the keystore password.
-
xpack.security.http.ssl.truststore.path
-
(Static) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file.
You cannot use this setting and
ssl.certificate_authorities
at the same time. -
xpack.security.http.ssl.truststore.type
-
(Static)
Set this to
PKCS12
to indicate that the truststore is a PKCS#12 file. -
xpack.security.http.ssl.truststore.password
-
(Static) The password for the truststore.
You cannot use this setting and
ssl.truststore.secure_password
at the same time. -
xpack.security.http.ssl.truststore.secure_password
- (Secure) Password for the truststore.
Transport TLS/SSL settings
editYou can configure the following TLS/SSL settings.
-
xpack.security.transport.ssl.enabled
-
(Static)
Used to enable or disable TLS/SSL on the transport networking layer, which nodes use to communicate with each other. The default is
false
. -
xpack.security.transport.ssl.supported_protocols
-
(Static) Supported protocols with versions. Valid protocols:
SSLv2Hello
,SSLv3
,TLSv1
,TLSv1.1
,TLSv1.2
,TLSv1.3
. If the JVM’s SSL provider supports TLSv1.3, the default isTLSv1.3,TLSv1.2,TLSv1.1
. Otherwise, the default isTLSv1.2,TLSv1.1
.Elasticsearch relies on your JDK’s implementation of SSL and TLS. View Supported SSL/TLS versions by JDK version for more information.
If
xpack.security.fips_mode.enabled
istrue
, you cannot useSSLv2Hello
orSSLv3
. See FIPS 140-2. -
xpack.security.transport.ssl.client_authentication
-
(Static)
Controls the server’s behavior in regard to requesting a certificate
from client connections. Valid values are
required
,optional
, andnone
.required
forces a client to present a certificate, whileoptional
requests a client certificate but the client is not required to present one. Defaults torequired
. -
xpack.security.transport.ssl.verification_mode
-
(Static) Defines how to verify the certificates presented by another party in the TLS connection:
Valid values
-
full
-
Validates that the provided certificate: has an issue date that’s
within the
not_before
andnot_after
dates; chains to a trusted Certificate Authority (CA); has ahostname
or IP address that matches the names within the certificate. -
certificate
-
Validates the provided certificate and verifies that it’s signed by a
trusted authority (CA), but doesn’t check the certificate
hostname
. -
none
-
Performs no certificate validation.
Setting certificate validation to
none
disables many security benefits of SSL/TLS, which is very dangerous. Only set this value if instructed by Elastic Support as a temporary diagnostic mechanism when attempting to resolve TLS errors.
Defaults to
full
. -
-
xpack.security.transport.ssl.cipher_suites
-
(Static) Supported cipher suites vary depending on which version of Java you use. For example, for version 12 the default value is
TLS_AES_256_GCM_SHA384
,TLS_AES_128_GCM_SHA256
,TLS_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
,TLS_RSA_WITH_AES_256_GCM_SHA384
,TLS_RSA_WITH_AES_128_GCM_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA256
,TLS_RSA_WITH_AES_128_CBC_SHA256
,TLS_RSA_WITH_AES_256_CBC_SHA
,TLS_RSA_WITH_AES_128_CBC_SHA
.For more information, see Oracle’s Java Cryptography Architecture documentation.
Transport TLS/SSL key and trusted certificate settings
editThe 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. A private key and certificate must be configured.
PEM encoded files
editWhen using PEM encoded files, use the following settings:
-
xpack.security.transport.ssl.key
-
(Static) Path to a PEM encoded file containing the private key.
If HTTP client authentication is required, it uses this file. You cannot use this setting and
ssl.keystore.path
at the same time. -
xpack.security.transport.ssl.key_passphrase
-
(Static) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
You cannot use this setting and
ssl.secure_key_passphrase
at the same time. -
xpack.security.transport.ssl.secure_key_passphrase
- (Secure) The passphrase that is used to decrypt the private key. Since the key might not be encrypted, this value is optional.
-
xpack.security.transport.ssl.certificate
-
(Static) Specifies the path for the PEM encoded certificate (or certificate chain) that is associated with the key.
This setting can be used only if
ssl.key
is set. -
xpack.security.transport.ssl.certificate_authorities
-
(Static) List of paths to PEM encoded certificate files that should be trusted.
This setting and
ssl.truststore.path
cannot be used at the same time.
Java keystore files
editWhen 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
-
(Static) The path for the keystore file that contains a private key and certificate.
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
ssl.key
at the same time. -
xpack.security.transport.ssl.keystore.password
- (Static) The password for the keystore.
-
xpack.security.transport.ssl.keystore.secure_password
- (Secure) The password for the keystore.
-
xpack.security.transport.ssl.keystore.key_password
-
(Static) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.secure_password
at the same time. -
xpack.security.transport.ssl.keystore.secure_key_password
- (Secure) The password for the key in the keystore. The default is the keystore password.
-
xpack.security.transport.ssl.truststore.path
-
(Static) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file.
You cannot use this setting and
ssl.certificate_authorities
at the same time. -
xpack.security.transport.ssl.truststore.password
-
(Static) The password for the truststore.
You cannot use this setting and
ssl.truststore.secure_password
at the same time. -
xpack.security.transport.ssl.truststore.secure_password
- (Secure) Password for the truststore.
PKCS#12 files
editElasticsearch can be configured to use PKCS#12 container files (.p12
or .pfx
files)
that contain the private key, certificate and certificates that should be trusted.
PKCS#12 files are configured in the same way as Java keystore files:
-
xpack.security.transport.ssl.keystore.path
-
(Static) The path for the keystore file that contains a private key and certificate.
It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
ssl.key
at the same time. -
xpack.security.transport.ssl.keystore.type
-
(Static)
The format of the keystore file. It must be either
jks
orPKCS12
. If the keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults toPKCS12
. Otherwise, it defaults tojks
. -
xpack.security.transport.ssl.keystore.password
- (Static) The password for the keystore.
-
xpack.security.transport.ssl.keystore.secure_password
- (Secure) The password for the keystore.
-
xpack.security.transport.ssl.keystore.key_password
-
(Static) The password for the key in the keystore. The default is the keystore password.
You cannot use this setting and
ssl.keystore.secure_password
at the same time. -
xpack.security.transport.ssl.keystore.secure_key_password
- (Secure) The password for the key in the keystore. The default is the keystore password.
-
xpack.security.transport.ssl.truststore.path
-
(Static) The path for the keystore that contains the certificates to trust. It must be either a Java keystore (jks) or a PKCS#12 file.
You cannot use this setting and
ssl.certificate_authorities
at the same time. -
xpack.security.transport.ssl.truststore.type
-
(Static)
Set this to
PKCS12
to indicate that the truststore is a PKCS#12 file. -
xpack.security.transport.ssl.truststore.password
-
(Static) The password for the truststore.
You cannot use this setting and
ssl.truststore.secure_password
at the same time. -
xpack.security.transport.ssl.truststore.secure_password
- (Secure) Password for the truststore.
Transport profile TLS/SSL settings
editThe 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 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
.
IP filtering settings
editYou can configure the following settings for IP filtering.
-
xpack.security.transport.filter.allow
- (Dynamic) List of IP addresses to allow.
-
xpack.security.transport.filter.deny
- (Dynamic) List of IP addresses to deny.
-
xpack.security.http.filter.allow
- (Dynamic) List of IP addresses to allow just for HTTP.
-
xpack.security.http.filter.deny
- (Dynamic) List of IP addresses to deny just for HTTP.
-
transport.profiles.$PROFILE.xpack.security.filter.allow
- (Dynamic) List of IP addresses to allow for this profile.
-
transport.profiles.$PROFILE.xpack.security.filter.deny
- (Dynamic) List of IP addresses to deny for this profile.
User cache and password hash algorithms
editCertain realms store user credentials in memory. To limit exposure
to credential theft and mitigate credential compromise, the cache only stores
a hashed version of the user credentials in memory. By default, the user cache
is hashed with a salted sha-256
hash algorithm. You can use a different
hashing algorithm by setting the static
cache.hash_algo
realm settings to any of the following values:
Table 1. Cache hash algorithms
Algorithm |
Description |
||
|
Uses a salted |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Doesn’t hash the credentials and keeps it in clear text in
memory. CAUTION: keeping clear text is considered insecure
and can be compromised at the OS level (for example through
memory dumps and using |
Likewise, realms that store passwords hash them using cryptographically strong
and password-specific salt values. You can configure the algorithm for password
hashing by setting the static
xpack.security.authc.password_hashing.algorithm
setting to one of the
following:
Table 2. Password hashing algorithms
Algorithm | Description | ||
---|---|---|---|
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |
||
|
Uses |