By default, the Elasticsearch security features are disabled when you have a basic or
trial license. To enable security features, use the xpack.security.enabled
setting.
You 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.
xpack.security.enabled
Set to true
to enable Elasticsearch security features on the node.
If set to false
, which is the default value for basic and trial licenses,
security features are disabled. It also affects all Kibana instances that
connect to this Elasticsearch instance; you do not need to disable security features in
those kibana.yml
files. For more information about disabling security features
in specific Kibana instances, see
Kibana security settings.
If you have gold or higher licenses, the default value is true
; we
recommend that you explicitly add this setting to avoid confusion.
xpack.security.hide_settings
xpack.security.authc.realms.active_directory.ad1.*
.
The API already omits all ssl
settings, bind_dn
, and bind_password
due to
the sensitive nature of the information.
xpack.security.fips_mode.enabled
true
if you run this Elasticsearch instance in a FIPS 140-2 enabled JVM. For more information, see FIPS 140-2. Defaults to false
.
xpack.security.authc.accept_default_password
elasticsearch.yml
, set this to false
to disable support for the default "changeme" password.
xpack.security.authc.password_hashing.algorithm
bcrypt
.
You can configure the following anonymous access settings in
elasticsearch.yml
. For more information, see
Enabling anonymous access.
xpack.security.authc.anonymous.username
_es_anonymous_user
.
xpack.security.authc.anonymous.roles
xpack.security.authc.anonymous.authz_exception
true
, an HTTP 403 response is returned if the anonymous user
does not have the appropriate permissions for the requested action. The
user is not prompted to provide credentials to access the requested
resource. When set to false
, an HTTP 401 response is returned and the user
can provide credentials with the appropriate permissions to gain
access. Defaults to true
.
In 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
100,000
.
xpack.security.automata.cache.enabled
true
.
xpack.security.automata.cache.size
10,000
.
xpack.security.automata.cache.ttl
48h
(48 hours).
You can set the following document and field level security
settings in elasticsearch.yml
. For more information, see
Setting up document and field
level security.
xpack.security.dls_fls.enabled
false
to prevent document and field level security
from being configured. Defaults to true
.
You can set the following token service settings in
elasticsearch.yml
.
xpack.security.authc.token.enabled
false
to disable the built-in token service. Defaults to true
unless
xpack.security.http.ssl.enabled
is false
. This prevents sniffing the token
from a connection over plain http.
xpack.security.authc.token.timeout
20m
or
20 minutes. The maximum value is 1 hour.
You can set the following API key service settings in
elasticsearch.yml
.
xpack.security.authc.api_key.enabled
false
to disable the built-in API key service. Defaults to true
unless
xpack.security.http.ssl.enabled
is false
. This prevents sniffing the API key
from a connection over plain http.
xpack.security.authc.api_key.hashing.algorithm
pbkdf2
.
xpack.security.authc.api_key.cache.ttl
1d
.
xpack.security.authc.api_key.cache.max_keys
xpack.security.authc.api_key.cache.hash_algo
ssha256
.
You 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 ... ...
The valid settings vary depending on the realm type. For more information, see Setting up authentication.
type
native, `ldap
, active_directory
, pki
, or file
. Required.
order
Integer.MAX_VALUE
.
enabled
true
.
For a native realm, the type
must be set to native
. In addition to the
settings that are valid for all realms, you can specify
the following optional settings:
cache.ttl
20m
.
cache.max_users
cache.hash_algo
ssha256
.
authentication.enabled
false
, disables authentication support in
this realm, so that it only supports user lookups.
(See the run as and
authorization realms features).
Defaults to true
.
The type
setting must be set to file
. In addition to the
settings that are valid for all realms, you can specify
the following settings:
cache.ttl
20m
. Specify values
using the standard Elasticsearch time units.
Defaults to 20m
.
cache.max_users
cache.hash_algo
ssha256
.
authentication.enabled
false
, disables authentication support in
this realm, so that it only supports user lookups.
(See the run as and
authorization realms features).
Defaults to true
.
The type
setting must be set to ldap
. In addition to the
Settings valid for all realms, you can specify the following settings:
url
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
and ldaps
protocols.
load_balance.type
failover
.
load_balance.cache_ttl
dns_failover
or dns_round_robin
as the load balancing type,
this setting controls the amount of time to cache DNS lookups. Defaults
to 1h
.
bind_dn
bind_dn
is not
exposed via the nodes info API.
bind_password
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)
user_dn_templates
{0}
.
This setting is multivalued; you can specify multiple user contexts.
Required to operate in user template mode. If user_search.base_dn
is specified,
this setting is not valid. For more information on
the different modes, see LDAP realms.
authorization_realms
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, the
user_dn_templates
settings are ignored.
user_group_attribute
group_search
settings are specified, this setting is ignored. Defaults
to memberOf
.
user_search.base_dn
user_dn_templates
is specified, this
setting is not valid. For more information on
the different modes, see LDAP realms.
user_search.scope
sub_tree
, one_level
or
base
. one_level
only searches objects directly contained within the
base_dn
. sub_tree
searches all objects contained under base_dn
.
base
specifies that the base_dn
is the user object, and that it is
the only user considered. Defaults to sub_tree
.
user_search.filter
(uid={0})
.
{0}
is substituted with the username provided when searching.
user_search.attribute
user_search.filter
instead.
The attribute to match with the username sent with the request. Defaults to uid
.
user_search.pool.enabled
false
, a new
connection is created for every search. The
default is true
when bind_dn
is set.
user_search.pool.size
20
.
user_search.pool.initial_size
0
. If the LDAP server is down, values greater than 0
could cause
startup failures.
user_search.pool.health_check.enabled
true
.
user_search.pool.health_check.dn
bind_dn
if present; if
not, falls back to user_search.base_dn
.
user_search.pool.health_check.interval
60s
.
group_search.base_dn
user_group_attribute
set on the user in order to determine group membership.
group_search.scope
sub_tree
, one_level
or
base
. one_level
only searches objects directly contained within the
base_dn
. sub_tree
searches all objects contained under base_dn
.
base
specifies that the base_dn
is a group object, and that it is the
only group considered. Defaults to sub_tree
.
group_search.filter
group
, groupOfNames
, groupOfUniqueNames
,
or posixGroup
with the attributes member
, memberOf
, or memberUid
. Any
instance of {0}
in the filter is replaced by the user attribute defined in
group_search.user_attribute
.
group_search.user_attribute
unmapped_groups_as_roles
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 to false
.
files.role_mapping
ES_PATH_CONF/role_mapping.yml
.
follow_referrals
true
.
metadata
timeout.tcp_connect
s
at the end indicates seconds, or ms
indicates milliseconds.
Defaults to 5s
(5 seconds ).
timeout.tcp_read
s
at the end indicates seconds, or ms
indicates milliseconds.
Defaults to 5s
(5 seconds ).
timeout.ldap_search
s
at the end indicates seconds, or ms
indicates milliseconds.
Defaults to 5s
(5 seconds ).
ssl.key
ssl.key
and ssl.keystore.path
cannot be used at the same time.
ssl.key_passphrase
ssl.secure_key_passphrase
(Secure)
ssl.certificate
ssl.certificate_authorities
ssl.certificate_authorities
and ssl.truststore.path
cannot be used at the
same time.
ssl.keystore.path
ssl.key
and ssl.keystore.path
may not be used at the same time.
ssl.keystore.type
jks
to use the Java
Keystore format, PKCS12
to use PKCS#12 files, or PKCS11
to use a PKCS#11 token.
The default is jks
.
ssl.keystore.password
ssl.keystore.secure_password
(Secure)
ssl.keystore.key_password
ssl.keystore.secure_key_password
ssl.truststore.path
ssl.certificate_authorities
and ssl.truststore.path
cannot be used at the same time.
ssl.truststore.password
ssl.truststore.secure_password
(Secure)
ssl.truststore.type
jks
to use the Java
Keystore format, PKCS12
to use PKCS#12 files, or PKCS11
to use a PKCS#11 token.
The default is jks
.
ssl.verification_mode
Indicates the type of verification when using ldaps
to protect against man
in the middle attacks and certificate forgery. Values are none
, certificate
,
and full
. Defaults to full
.
See ssl.verification_mode
for an explanation of these values.
ssl.supported_protocols
TLSv1.3,TLSv1.2,TLSv1.1
if
the JVM supports TLSv1.3, otherwise TLSv1.2,TLSv1.1
.
ssl.cipher_suites
ssl.cipher_suites
for the default value.
cache.ttl
20m
.
cache.max_users
100000
.
cache.hash_algo
ssha256
.
authentication.enabled
false
, disables authentication support in
this realm, so that it only supports user lookups.
(See the run as and
authorization realms features).
Defaults to true
.
The type
setting must be set to active_directory
. In addition to the
settings that are valid for all realms, you can specify
the following settings:
url
One or more LDAP URLs in the ldap[s]://<server>:<port>
format. Defaults to
ldap://<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
and ldaps
protocols.
If no URL is provided, Elasticsearch uses a default of ldap://<domain_name>:389
. This
default uses the domain_name
setting value and assumes an unencrypted
connection to port 389.
load_balance.type
failover
.
load_balance.cache_ttl
dns_failover
or dns_round_robin
as the load balancing type,
this setting controls the amount of time to cache DNS lookups. Defaults
to 1h
.
domain_name
url
and the user_search_dn
settings are not specified, the cluster can derive those values from this
setting. Required.
bind_dn
bind_dn
is not
exposed via the nodes info API.
bind_password
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)
unmapped_groups_as_roles
true
, the names of any unmapped Active Directory groups are used as
role names and assigned to the user. A group is considered unmapped when it
is not referenced in any role-mapping files. API-based role mappings are not
considered. Defaults to false
.
files.role_mapping
ES_PATH_CONF/role_mapping.yml
.
user_search.base_dn
user_search.scope
sub_tree
, one_level
or base
.
one_level
only searches users directly contained within the base_dn
.
sub_tree
searches all objects contained under base_dn
. base
specifies that the base_dn
is a user object, and that it is the
only user considered. Defaults to sub_tree
.
user_search.filter
user
objects with either sAMAccountName
or
userPrincipalName
. If specified, this must be a valid LDAP user search filter.
For example (&(objectClass=user)(sAMAccountName={0}))
. For more information,
see
Search Filter Syntax.
user_search.upn_filter
user
objects with
a matching userPrincipalName
. If specified, this
must be a valid LDAP user search filter. For example,
(&(objectClass=user)(userPrincipalName={1}))
. {1}
is the full user principal name
provided by the user. For more information, see
Search Filter Syntax.
user_search.down_level_filter
user
objects with a matching
sAMAccountName
in the domain provided. If specified, this
must be a valid LDAP user search filter. For example,
(&(objectClass=user)(sAMAccountName={0}))
. For more information, see
Search Filter Syntax.
user_search.pool.enabled
true
when bind_dn
is provided.
user_search.pool.size
20
.
user_search.pool.initial_size
0
. If the LDAP server is down, values greater than 0
could cause startup failures.
user_search.pool.health_check.enabled
true
.
user_search.pool.health_check.dn
bind_dn
if that setting is present. Otherwise, it
defaults to the value of the user_search.base_dn
setting.
user_search.pool.health_check.interval
60s
.
group_search.base_dn
group_search.scope
sub_tree
, one_level
or
base
. one_level
searches for groups directly contained within the
base_dn
. sub_tree
searches all objects contained under base_dn
.
base
specifies that the base_dn
is a group object, and that it is
the only group considered. Defaults to sub_tree
.
metadata
timeout.tcp_connect
s
at the end indicates seconds, or ms
indicates milliseconds.
Defaults to 5s
(5 seconds ).
timeout.tcp_read
s
at the end indicates seconds, or ms
indicates milliseconds.
Defaults to 5s
(5 seconds ).
timeout.ldap_search
s
at the end indicates seconds, or ms
indicates milliseconds.
Defaults to 5s
(5 seconds ).
ssl.certificate
ssl.certificate_authorities
ssl.certificate_authorities
and ssl.truststore.path
cannot be used at the
same time.
ssl.key
ssl.key
and
ssl.keystore.path
cannot be used at the same time.
ssl.key_passphrase
ssl.secure_key_passphrase
(Secure)
ssl.keystore.key_password
ssl.keystore.secure_key_password
(Secure)
ssl.keystore.password
ssl.secure_keystore.password
(Secure)
ssl.keystore.path
ssl.key
and ssl.keystore.path
cannot be used at the same time.
ssl.keystore.type
jks
to use the Java
Keystore format, PKCS12
to use PKCS#12 files, or PKCS11
to use a PKCS#11 token.
The default is jks
.
ssl.truststore.password
ssl.truststore.secure_password
(Secure)
ssl.truststore.path
ssl.certificate_authorities
and ssl.truststore.path
cannot be used at the
same time.
ssl.truststore.type
jks
to use the Java
Keystore format, PKCS12
to use PKCS#12 files, or PKCS11
to use a PKCS#11 token.
The default is jks
.
ssl.verification_mode
Indicates the type of verification when using ldaps
to protect against man
in the middle attacks and certificate forgery. Values are none
, certificate
,
and full
. Defaults to full
.
See ssl.verification_mode
for an explanation of these values.
ssl.supported_protocols
TLSv1.3,TLSv1.2,TLSv1.1
if
the JVM supports TLSv1.3, otherwise TLSv1.2,TLSv1.1
.
ssl.cipher_suites
ssl.cipher_suites
for
the default values.
cache.ttl
20m
.
cache.max_users
100000
.
cache.hash_algo
ssha256
.
authentication.enabled
false
, disables authentication support in
this realm, so that it only supports user lookups.
(See the run as and
authorization realms features).
Defaults to true
.
follow_referrals
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 as search
). Defaults to true
.
The type
setting must be set to pki
. In addition to the
settings that are valid for all realms, you can specify
the following settings:
username_pattern
CN=(.*?)(?:,\|$)
.
certificate_authorities
truststore.path
.
truststore.algorithm
SunX509
.
truststore.password
truststore.path
is set.
truststore.secure_password
(Secure)
truststore.path
certificate_authorities
.
files.role_mapping
ES_PATH_CONF/role_mapping.yml
.
authorization_realms
cache.ttl
20m
.
cache.max_users
100000
.
The type
setting must be set to saml
. In addition to the
settings that are valid for all realms, you can specify
the following settings:
idp.entity_id
urn:example.com:idp
) and can be found in the configuration or the SAML
metadata of the Identity Provider.
idp.metadata.path
file
URL or a https
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’s
idp.metadata.http.refresh
setting.
idp.metadata.http.refresh
https
metadata is checked for changes.
Defaults to 1h
(1 hour).
idp.use_single_logout
true
.
sp.entity_id
https://kibana.example.com/
.
sp.acs
https://kibana.example.com/api/security/v1/saml
.
sp.logout
https://kibana.example.com/logout
.
attributes.principal
attributes.groups
attributes.name
attributes.mail
attributes.dn
attribute_patterns.principal
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
attribute_patterns.principal
, but for the group property.
attribute_patterns.name
attribute_patterns.principal
, but for the name property.
attribute_patterns.mail
attribute_patterns.principal
, but for the mail property.
attribute_patterns.dn
attribute_patterns.principal
, but for the dn property.
nameid_format
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
).
nameid.allow_create
AllowCreate
attribute of the
NameIdPolicy
element in an authentication request. Defaults to false
.
nameid.sp_qualifier
SPNameQualifier
attribute of the
NameIdPolicy
element in an authentication request. The default is to not
include the SPNameQualifier
attribute.
force_authn
ForceAuthn
attribute when requesting that the IdP
authenticate the current user. If set to true
, the IdP is required to verify
the user’s identity, irrespective of any existing sessions they might have.
Defaults to false
.
populate_user_metadata
true
.
authorization_realms
allowed_clock_skew
3m
(3 minutes).
req_authn_context_class_ref
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.
If 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
*
to sign all messages.
Each element in the list should be the local name of a SAML XML Element.
Supported element types are AuthnRequest
, LogoutRequest
and LogoutResponse
.
Only valid if signing.key
or signing.keystore.path
is also specified.
Defaults to *
.
signing.key
signing.key
and signing.keystore.path
cannot be used at the same time.
signing.secure_key_passphrase
(Secure)
signing.key
)
if it is encrypted.
signing.certificate
signing.key
. This certificate must also be included in the
Service Provider metadata or manually configured within the IdP to allow for
signature validation. This setting can only be used if signing.key
is set.
signing.keystore.path
signing.key
and signing.keystore.path
cannot be used at the same time.
signing.keystore.type
signing.keystore.path
.
Must be either jks
or PKCS12
. If the keystore path ends in ".p12", ".pfx",
or "pkcs12", this setting defaults to PKCS12
. Otherwise, it defaults to jks
.
signing.keystore.alias
signing.keystore.secure_password
(Secure)
signing.keystore.path
.
signing.keystore.secure_key_password
(Secure)
signing.keystore.path
).
Defaults to the keystore password.
If 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
encryption.key
and encryption.keystore.path
cannot be used at the same time.
encryption.secure_key_passphrase
(Secure)
encryption.key
) if it is encrypted.
encryption.certificate
encryption.key
. This certificate must also be included in
the Service Provider metadata or manually configured within the IdP to enable
message encryption. This setting can be used only if encryption.key
is set.
encryption.keystore.path
encryption.key
and encryption.keystore.path
cannot be used at the same time.
encryption.keystore.type
encryption.keystore.path
).
Must be either jks
or PKCS12
. If the keystore path ends in ".p12", ".pfx",
or "pkcs12", this setting defaults to PKCS12
. Otherwise, it defaults to jks
.
encryption.keystore.alias
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)
encryption.keystore.path
).
encryption.keystore.secure_key_password
(Secure)
encryption.keystore.path
). Only a
single password is supported. If you are using multiple decryption keys,
they cannot have individual passwords.
If you are loading the IdP metadata over SSL/TLS (that is, idp.metadata.path
is a URL using the https
protocol), the following settings can be used to
configure SSL. If these are not specified, then the
default SSL settings are used.
These settings are not used for any purpose other than loading metadata over https.
ssl.key
ssl.key
and ssl.keystore.path
cannot be used
at the same time.
ssl.key_passphrase
ssl.key
) if it is
encrypted. Cannot be used with ssl.secure_key_passphrase
.
ssl.secure_key_passphrase
(Secure)
ssl.key
) if it is
encrypted. Cannot be used with ssl.key_passphrase
.
ssl.certificate
ssl.key
). This setting can be used only if ssl.key
is set.
ssl.certificate_authorities
ssl.certificate_authorities
and ssl.truststore.path
cannot be
used at the same time.
ssl.keystore.path
ssl.key
and ssl.keystore.path
cannot be used at the same time.
ssl.keystore.type
ssl.keystore.path
). Must be either jks
or PKCS12
.
If the keystore path ends in ".p12", ".pfx" or "pkcs12", this setting defaults
to PKCS12
. Otherwise, it defaults to jks
.
ssl.keystore.password
ssl.keystore.path
). This setting cannot be used
with ssl.keystore.secure_password
.
ssl.keystore.secure_password
(Secure)
ssl.keystore.path
).
This setting cannot be used with ssl.keystore.password
.
ssl.keystore.key_password
ssl.keystore.path
).
Defaults to the keystore password. This setting cannot be used with
ssl.keystore.secure_key_password
.
ssl.keystore.secure_key_password
(Secure)
ssl.keystore.path
).
Defaults to the keystore password. This setting cannot be used with
ssl.keystore.key_password
.
ssl.truststore.path
ssl.certificate_authorities
and ssl.truststore.path
cannot be used at the
same time.
ssl.truststore.type
ssl.truststore.path
). Must be either jks
or
PKCS12
. If the keystore path ends in ".p12", ".pfx" or "pkcs12", this setting
defaults to PKCS12
. Otherwise, it defaults to jks
.
ssl.truststore.password
ssl.truststore.path
). This setting cannot be
used with ssl.truststore.secure_password
.
ssl.truststore.secure_password
(Secure)
ssl.truststore.path
). This setting cannot be
used with ssl.truststore.password
.
ssl.verification_mode
One of full
(verify the hostname and the certificate path), certificate
(verify the
certificate path, but not the hostname) or none
(perform no verification).
Defaults to full
.
See ssl.verification_mode
for a more detailed explanation of these values.
ssl.supported_protocols
TLSv1.3,TLSv1.2,TLSv1.1
if
the JVM supports TLSv1.3, otherwise TLSv1.2,TLSv1.1
.
ssl.cipher_suites
For a Kerberos realm, the type
must be set to kerberos
. In addition to the
settings that are valid for all realms, you can specify
the following settings:
keytab.path
remove_realm_name
true
to remove the realm part of principal names.
Principal names in Kerberos have the form user/instance@REALM
. If this option
is true
, the realm part (@REALM
) will not be included in the username.
Defaults to false
.
krb.debug
true
to enable debug logs for the Java login module that
provides support for Kerberos authentication. Defaults to false
.
cache.ttl
20m
.
cache.max_users
authorization_realms
The load_balance.type
setting can have the following values:
failover
: The URLs specified are used in the order that they are specified.
The first server that can be connected to will be used for all subsequent
connections. If a connection to that server fails then the next server that a
connection can be established to will be used for subsequent connections.
dns_failover
: In this mode of operation, only a single URL may be specified.
This URL must contain a DNS name. The system will be queried for all IP
addresses that correspond to this DNS name. Connections to the Active Directory
or LDAP server will always be tried in the order in which they were retrieved.
This differs from failover
in that there is no reordering of the list and if a
server has failed at the beginning of the list, it will still be tried for each
subsequent connection.
round_robin
: Connections will continuously iterate through the list of
provided URLs. If a server is unavailable, iterating through the list of URLs
will continue until a successful connection is made.
dns_round_robin
: In this mode of operation, only a single URL may be
specified. This URL must contain a DNS name. The system will be queried for all
IP addresses that correspond to this DNS name. Connections will continuously
iterate through the list of addresses. If a server is unavailable, iterating
through the list of URLs will continue until a successful connection is made.
In general, the values below represent the default values for the various TLS settings. For more information, see Encrypting communications.
ssl.supported_protocols
Supported protocols with versions. Valid protocols: SSLv2Hello
,
SSLv3
, TLSv1
, TLSv1.1
, TLSv1.2
, TLSv1.3
. Defaults to TLSv1.3,TLSv1.2,TLSv1.1
if
the JVM supports TLSv1.3, otherwise TLSv1.2,TLSv1.1
.
If xpack.security.fips_mode.enabled
is true
, you cannot use SSLv2Hello
or SSLv3
. See FIPS 140-2.
ssl.client_authentication
required
, optional
, and none
.
required
forces a client to present a certificate, while optional
requests a client certificate but the client is not required to present one.
Defaults to required
, except for HTTP, which defaults to none
. See
HTTP TLS/SSL Settings.
ssl.verification_mode
Controls the verification of certificates. Valid values are:
full
, which verifies that the provided certificate is signed by a trusted
authority (CA) and also verifies that the server’s hostname (or IP
address) matches the names identified within the certificate.
certificate
, which verifies that the provided certificate is signed by a
trusted authority (CA), but does not perform any hostname verification.
none
, which performs no verification of the server’s certificate. This mode
disables many of the security benefits of SSL/TLS and should only be
used after very careful consideration. It is primarily intended as a
temporary diagnostic mechanism when attempting to resolve TLS errors,
and its use on production clusters is strongly discouraged.
The default value is full
.
ssl.cipher_suites
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
,
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
,
TLS_RSA_WITH_AES_128_CBC_SHA256
, TLS_RSA_WITH_AES_128_CBC_SHA
. If the Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files has been installed, the default value also includes TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
,
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
,
TLS_RSA_WITH_AES_256_CBC_SHA256
, TLS_RSA_WITH_AES_256_CBC_SHA
.
The following settings are used to specify a private key, certificate, and the trusted certificates that should be used when communicating over an SSL/TLS connection. If 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.
You can configure the following TLS/SSL settings. If the settings are not configured, the Default TLS/SSL Settings are used.
xpack.security.http.ssl.enabled
false
.
xpack.security.http.ssl.supported_protocols
SSLv2Hello
,
SSLv3
, TLSv1
, TLSv1.1
, TLSv1.2
, TLSv1.3
. Defaults to TLSv1.3,TLSv1.2,TLSv1.1
if
the JVM supports TLSv1.3, otherwise TLSv1.2,TLSv1.1
.
xpack.security.http.ssl.client_authentication
required
, optional
, and none
.
required
forces a client to present a certificate, while optional
requests a client certificate but the client is not required to present one.
Defaults to none
.
xpack.security.http.ssl.cipher_suites
The following settings are used to specify a private key, certificate, and the trusted certificates that should be used when communicating over an SSL/TLS connection. A private key and certificate must be configured. If none of the settings below are specified, the Default TLS/SSL Settings are used.
When using PEM encoded files, use the following settings:
xpack.security.http.ssl.key
xpack.security.http.ssl.key_passphrase
xpack.security.http.ssl.secure_key_passphrase
(Secure)
xpack.security.http.ssl.certificate
xpack.security.http.ssl.certificate_authorities
When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings:
xpack.security.http.ssl.keystore.path
xpack.security.http.ssl.keystore.password
xpack.security.http.ssl.keystore.secure_password
(Secure)
xpack.security.http.ssl.keystore.key_password
xpack.security.http.ssl.keystore.password
.
xpack.security.http.ssl.keystore.secure_key_password
(Secure)
xpack.security.http.ssl.truststore.path
xpack.security.http.ssl.truststore.password
xpack.security.http.ssl.truststore.secure_password
(Secure)
Elasticsearch 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
xpack.security.http.ssl.keystore.type
PKCS12
to indicate that the keystore is a PKCS#12 file.
xpack.security.http.ssl.keystore.password
xpack.security.http.ssl.keystore.secure_password
(Secure)
xpack.security.http.ssl.keystore.key_password
xpack.security.http.ssl.keystore.password
.
xpack.security.http.ssl.keystore.secure_key_password
(Secure)
xpack.security.http.ssl.truststore.path
xpack.security.http.ssl.truststore.type
PKCS12
to indicate that the truststore is a PKCS#12 file.
xpack.security.http.ssl.truststore.password
xpack.security.http.ssl.truststore.secure_password
(Secure)
Elasticsearch can be configured to use a PKCS#11 token that contains the private key, certificate and certificates that should be trusted.
PKCS#11 token require additional configuration on the JVM level and can be enabled via the following settings:
xpack.security.http.keystore.type
PKCS11
to indicate that the PKCS#11 token should be used as a keystore.
xpack.security.http.truststore.type
PKCS11
to indicate that the PKCS#11 token should be used as a truststore.
When configuring the PKCS#11 token that your JVM is configured to use as
a keystore or a truststore for Elasticsearch, the PIN for the token can be
configured by setting the appropriate value to ssl.truststore.password
or ssl.truststore.secure_password
in the context that you are configuring.
Since there can only be one PKCS#11 token configured, only one keystore and
truststore will be usable for configuration in Elasticsearch. This in turn means
that only one certificate can be used for TLS both in the transport and the
http layer.
You can configure the following TLS/SSL settings. If the settings are not configured, the Default TLS/SSL Settings are used.
xpack.security.transport.ssl.enabled
false
.
xpack.security.transport.ssl.supported_protocols
SSLv2Hello
,
SSLv3
, TLSv1
, TLSv1.1
, TLSv1.2
, TLSv1.3
. Defaults to TLSv1.3,TLSv1.2,TLSv1.1
if
the JVM supports TLSv1.3, otherwise TLSv1.2,TLSv1.1
.
xpack.security.transport.ssl.client_authentication
required
, optional
, and none
.
required
forces a client to present a certificate, while optional
requests a client certificate but the client is not required to present one.
Defaults to none`
.
xpack.security.transport.ssl.verification_mode
none
,
certificate
, and full
. Defaults to full
.
xpack.security.transport.ssl.cipher_suites
The following settings are used to specify a private key, certificate, and the trusted certificates that should be used when communicating over an SSL/TLS connection. A private key and certificate must be configured. If none of the settings below are specified, the Default TLS/SSL Settings are used.
When using PEM encoded files, use the following settings:
xpack.security.transport.ssl.key
xpack.security.transport.ssl.key_passphrase
xpack.security.transport.ssl.secure_key_passphrase
(Secure)
xpack.security.transport.ssl.certificate
xpack.security.transport.ssl.certificate_authorities
When using Java keystore files (JKS), which contain the private key, certificate and certificates that should be trusted, use the following settings:
xpack.security.transport.ssl.keystore.path
xpack.security.transport.ssl.keystore.password
xpack.security.transport.ssl.keystore.secure_password
(Secure)
xpack.security.transport.ssl.keystore.key_password
xpack.security.transport.ssl.keystore.password
.
xpack.security.transport.ssl.keystore.secure_key_password
(Secure)
xpack.security.transport.ssl.truststore.path
xpack.security.transport.ssl.truststore.password
xpack.security.transport.ssl.truststore.secure_password
(Secure)
Elasticsearch 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
xpack.security.transport.ssl.keystore.type
PKCS12
to indicate that the keystore is a PKCS#12 file.
xpack.security.transport.ssl.keystore.password
xpack.security.transport.ssl.keystore.secure_password
(Secure)
xpack.security.transport.ssl.keystore.key_password
xpack.security.transport.ssl.keystore.password
.
xpack.security.transport.ssl.keystore.secure_key_password
(Secure)
xpack.security.transport.ssl.truststore.path
xpack.security.transport.ssl.truststore.type
PKCS12
to indicate that the truststore is a PKCS#12 file.
xpack.security.transport.ssl.truststore.password
xpack.security.transport.ssl.truststore.secure_password
(Secure)
Elasticsearch can be configured to use a PKCS#11 token that contains the private key, certificate and certificates that should be trusted.
PKCS#11 token require additional configuration on the JVM level and can be enabled via the following settings:
xpack.security.transport.keystore.type
PKCS11
to indicate that the PKCS#11 token should be used as a keystore.
xpack.security.transport.truststore.type
PKCS11
to indicate that the PKCS#11 token should be used as a truststore.
When configuring the PKCS#11 token that your JVM is configured to use as
a keystore or a truststore for Elasticsearch, the PIN for the token can be
configured by setting the appropriate value to ssl.truststore.password
or ssl.truststore.secure_password
in the context that you are configuring.
Since there can only be one PKCS#11 token configured, only one keystore and
truststore will be usable for configuration in Elasticsearch. This in turn means
that only one certificate can be used for TLS both in the transport and the
http layer.
The same settings that are available for the default transport are also available for each transport profile. By default, the settings for a transport profile will be the same as the default transport unless they are specified.
As an example, lets look at the 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
.
You can configure the following settings for IP filtering.
xpack.security.transport.filter.allow
xpack.security.transport.filter.deny
xpack.security.http.filter.allow
xpack.security.http.filter.deny
transport.profiles.$PROFILE.xpack.security.filter.allow
transport.profiles.$PROFILE.xpack.security.filter.deny
Certain 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 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 | ||
| 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 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 |