OpenSearch/docs/en/settings/security-settings.asciidoc

[[security-settings]]
== Security Settings

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

[float]
[[general-security-settings]]
=== General Security Settings
`xpack.security.enabled`::
Set to `false` to disable {security}.
Configure in both `elasticsearch.yml` and `kibana.yml`. 

[float]
[[password-security-settings]]
=== Default Password Security Settings
`xpack.security.authc.accept_default_password`::
In `elasticsearch.yml`, set this to `false` to disable support for the default "changeme" password.
For more information, see <<disabling-default-password, Disable Default Password Functionality>>.

[float]
[[anonymous-access-settings]]
=== Anonymous Access Settings
You can configure the following anonymous access settings in 
`elasticsearch.yml`.  For more information, see <<anonymous-access, 
Enabling Anonymous Access>>.

`xpack.security.authc.anonymous.username`::
The username (principal) of the anonymous user. Defaults to `_es_anonymous_user`. 

`xpack.security.authc.anonymous.roles`::
The roles to associate with the anonymous user. Required.

`xpack.security.authc.anonymous.authz_exception`::
When `true`, an HTTP 403 response is returned if the anonymous user
does not have the appropriate permissions for the requested action. The
user is not prompted to provide credentials to access the requested
resource. When set to `false`, a HTTP 401 is returned and the user 
can provide credentials with the appropriate permissions to gain 
access. Defaults to `true`.

[float]
[[field-document-security-settings]]
=== Document and Field Level Security Settings

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

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

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

[source,yaml]
----------------------------------------
xpack.security.authc.realms:

    realm1:
        type: native
        order: 0
        ...

    realm2:
        type: ldap
        order: 1
        ...

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

The valid settings vary depending on the realm type. For more 
information, see <<setting-up-authentication, Setting Up Authentication>>.

[float]
==== Settings Valid for All Realms

`type`::  
The type of the realm: `native, `ldap`, `active_directory`, `pki`, or `file`. Required.

`order`::     
The priority of the realm within the realm chain. Defaults to `Integer.MAX_VALUE`. 

`enabled`::     
Enable/disable the realm. Defaults to `true`.

[[ref-users-settings]]

[float]
==== File Realm Settings

`cache.ttl`::       
The time-to-live for cached user entries--user credentials are cached for 
this configured period of time. Defaults to `20m`. Specify values using the
standard Elasticsearch {ref}/common-options.html#time-units[time units]. 
Defaults to `20m`.

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

`cache.hash_algo`::   
(Expert Setting) The hashing algorithm that is used for the in-memory cached 
user credentials. See the <<cache-hash-algo,Cache hash algorithms>> table f
or all possible values. Defaults to `ssha256`.

[[ref-ldap-settings]]
[float]
==== LDAP Realm Settings
`url`::                              
An LDAP URL in the format `ldap[s]://<server>:<port>`. Required.

`load_balance.type`::                     
The behavior to use when there are multiple LDAP URLs defined. For supported 
values see <<ldap-load-balancing, LDAP load balancing and failover types>>.
Defaults to `failover`.

`load_balance.cache_ttl`::                
When using `dns_failover` or `dns_round_robin` as the load balancing type, 
this setting controls the amount of time to cache DNS lookups. Defaults 
to `1h`.

`bind_dn`::                             
The DN of the user that will be used to bind to the LDAP and perform searches. 
If this is not specified, an anonymous bind will be attempted. 
Defaults to Empty.

`bind_password`::                    
The password for the user that will be used to bind to the LDAP. 
Defaults to Empty.

`user_dn_templates`::                      
The DN template that replaces the user name with the string `{0}`. 
This element is multivalued; you can specify multiple user contexts. 
Required to operate in user template mode. Not valid
if `user_search.base_dn` is specified. For more information on
the different modes, see <<ldap-realm, ldap realms>>. 

`user_group_attribute`::                      
Specifies the attribute to examine on the user for group membership. 
The default is `memberOf`. This setting will be ignored if any 
`group_search` settings are specified. Defaults to  `memberOf`.

`user_search.base_dn`::                     
Specifies a container DN to search for users. Required 
to operated in user search mode. Not valid if 
`user_dn_templates is specified. For more information on
the different modes, see <<ldap-realm, ldap realms>>.

`user_search.scope`::                         
The scope of the user search. Valid values are `sub_tree`, `one_level` or 
`base`. `one_level` only searches objects directly contained within the 
`base_dn`. `sub_tree` searches all objects contained under `base_dn`. 
`base` specifies that the `base_dn` is the user object, and that it is 
the only user considered. Defaults to  `sub_tree`.

`user_search.attribute`::                   
The attribute to match with the username presented to. Defaults to `uid`.

`user_search.pool.enabled`::
Enables or disables connection pooling for user search. When
disabled a new connection is created for every search. The
default is `true`.

`user_search.pool.size`::                   
The maximum number of connections to the LDAP server to allow in the 
connection pool. Defaults to `20`.

`user_search.pool.initial_size`::          
The initial number of connections to create to the LDAP server on startup.
Defaults to `5`.

`user_search.pool.health_check.enabled`::     
Flag to enable or disable a health check on LDAP connections in the connection 
pool. Connections are checked in the background at the specified interval.
Defaults to `true`.

`user_search.pool.health_check.dn`::       
The distinguished name to be retrieved as part of the health check. 
Defaults to the value of `bind_dn`. Required if `bind_dn` is not 
specified.

`user_search.pool.health_check.interval`::    
The interval to perform background checks of connections in the pool.
Defaults to `60s`.
`group_search.base_dn`::                   
The container DN to search for groups in which the user has membership. When 
this element is absent, Security searches for the attribute specified by 
`user_group_attribute` set on the user in order to determine group membership.

`group_search.scope`::                         
Specifies whether the group search should be `sub_tree`, `one_level` or 
`base`.  `one_level` only searches objects directly contained within the 
`base_dn`. `sub_tree` searches all objects contained under `base_dn`. 
`base` specifies that the `base_dn` is a group object, and that it is the 
only group considered. Defaults to  `sub_tree`.

`group_search.filter`::                     
When not set, the realm searches for `group`, `groupOfNames`, `groupOfUniqueNames`,
or `posixGroup` with the attributes `member`, `memberOf`, or `memberUid`.  Any
instance of `{0}` in the filter is replaced by the user attribute defined in
`group_search.user_attribute`.

`group_search.user_attribute`::             
Specifies the user attribute that will be fetched and provided as a parameter to 
the filter.  If not set, the user DN is passed into the filter. Defaults to Empty.

`unmapped_groups_as_roles`::                
Takes a boolean variable. When this element is set to `true`, the names of any 
LDAP groups that are not referenced in a role-mapping _file_ are used as role
names and assigned to the user. Defaults to `false`.

`files.role_mapping`::               
The <<security-files-location,location>> for the <<ldap-role-mapping, 
YAML role mapping configuration file>>. Defaults to  
`CONFIG_DIR/x-pack/role_mapping.yml`.

`follow_referrals`::                       
Boolean value that specifies whether Securityshould follow referrals returned 
by the LDAP server. Referrals are URLs returned by the server that are to be 
used to continue the LDAP operation (e.g. search). Defaults to `true`.

`metadata`::
A list of additional LDAP attributes that should be loaded from the
LDAP server and stored in the authenticated user's metadata field.

`timeout.tcp_connect`::
The TCP connect timeout period for establishing an LDAP connection.
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
Defaults to `5s` (5 seconds ).

`timeout.tcp_read`::
The TCP read timeout period after establishing an LDAP connection.
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
Defaults to `5s` (5 seconds ).

`timeout.ldap_search`::
The LDAP Server enforced timeout period for an LDAP search.
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
Defaults to `5s` (5 seconds ).

`ssl.key`::
Path to a PEM encoded file containing the private key.

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

`ssl.certificate`::
Path to a PEM encoded file containing the certificate (or certificate chain)
that will be presented to clients when they connect.

`ssl.certificate_authorities`::
List of paths to PEM encoded certificate files that should be trusted.

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

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

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

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

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

`ssl.verification_mode`::
Indicates the type of verification when using `ldaps` to protect against man
in the middle attacks and certificate forgery. Values are `none`, `certificate`,
and `full`. Defaults to the value of `xpack.ssl.verification_mode`.

`ssl.supported_protocols`::
Supported protocols with versions. Defaults to the value of
`xpack.ssl.supported_protocols`.

`ssl.cipher_suites`
Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[
Java Cryptography Architecture documentation]. Defaults to the value of
`xpack.ssl.cipher_suites`.

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

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

`cache.hash_algo`::                          
(Expert Setting) Specifies the hashing algorithm that is used for the 
in-memory cached user credentials (see <<cache-hash-algo,Cache hash algorithms>> 
table for all possible values). Defaults to `ssha256`.

[[ref-ad-settings]]
[float]
==== Active Directory Realm Settings

`url`::                        
A URL in the format `ldap[s]://<server>:<port>`. Defaults to `ldap://<domain_name>:389`. 

`load_balance.type`::         
The behavior to use when there are multiple LDAP URLs defined. For supported 
values see <<ad-load-balancing, LDAP load balancing and failover types>>.
Defaults to  `failover`.

`load_balance.cache_ttl`::     
When using `dns_failover` or `dns_round_robin` as the load balancing type, 
this setting controls the amount of time to cache DNS lookups. Defaults
to `1h`.

`domain_name`::                
The domain name of Active Directory. The cluster can derive the URL and 
`user_search_dn` fields from values in this element if those fields are not 
otherwise specified. Required.

`unmapped_groups_as_roles`::                                                         
Takes a boolean variable. When this element is set to `true`, the names of any
LDAP groups that are not referenced in a role-mapping _file_ are used as role
names and assigned to the user. Defaults to `false`.

`files.role_mapping`::         
The <<security-files-location,location>> for the <<ldap-role-mapping, YAML
role mapping configuration file>>. Defaults to  `CONFIG_DIR/x-pack/role_mapping.yml`. 

`user_search.base_dn`::        
The context to search for a user. Defaults to the root 
of the Active Directory domain. 

`user_search.scope`::          
Specifies whether the user search should be `sub_tree`, `one_level` or `base`.  
`one_level` only searches users directly contained within the `base_dn`. 
`sub_tree` searches all objects contained under `base_dn`. `base` 
specifies that the `base_dn` is a user object, and that it is the 
only user considered. Defaults to `sub_tree`.

`user_search.filter`::        
Specifies a filter to use to lookup a user given a username.  The default 
filter looks up `user` objects with either `sAMAccountName` or 
`userPrincipalName`.

`user_search.upn_filter`::
Specifies a filter to use to lookup a user given a user principal name.
The default filter looks up `user` objects with either
a matching `userPrincipalName` or a `sAMAccountName` matching the account
portion of the user principal name. If specified, this
must be a valid LDAP user search filter, for example
`(&(objectClass=user)(sAMAccountName={0}))`. `{0}` is the value preceding the
`@` sign in the user principal name and `{1}` is the full user principal name
provided by the user.

`user_search.down_level_filter`::
Specifies a filter to use to lookup a user given a down level logon name
(DOMAIN\user). The default filter looks up `user` objects with a matching
`sAMAccountName` in the domain provided. If specified, this
must be a valid LDAP user search filter, for example
`(&(objectClass=user)(sAMAccountName={0}))`.

`group_search.base_dn`::       
The context to search for groups in which the user has membership.  Defaults 
to the root of the  Active Directory domain.

`group_search.scope`::          
Specifies whether the group search should be `sub_tree`, `one_level` or 
`base`.  `one_level` searches for groups directly contained within the 
`base_dn`. `sub_tree` searches all objects contained under `base_dn`. 
`base` specifies that the `base_dn` is a group object, and that it is 
the only group considered. Defaults to `sub_tree`.

`metadata`::
A list of additional LDAP attributes that should be loaded from the
LDAP server and stored in the authenticated user's metadata field.

`timeout.tcp_connect`::
The TCP connect timeout period for establishing an LDAP connection.  
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
Defaults to `5s` (5 seconds ).

`timeout.tcp_read`::           
The TCP read timeout period after establishing an LDAP connection.  
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
Defaults to `5s` (5 seconds ).

`timeout.ldap_search`::       
The LDAP Server enforced timeout period for an LDAP search.  
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
Defaults to `5s` (5 seconds ).

`ssl.key`::
Path to the PEM encoded file containing the private key.

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

`ssl.certificate`::
Path to a PEM encoded file containing the certificate (or certificate chain)
that will be presented to clients when they connect.

`ssl.certificate_authorities`::
List of paths to PEM encoded certificate files that should be trusted.

`ssl.keystore.path`::
The path to the Java Keystore file that contains a private key and certificate.

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

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

`ssl.truststore.path`::
The path to the Java Keystore file that contains the certificates to trust.

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

`ssl.verification_mode`::
Indicates the type of verification when using `ldaps` to protect against man
in the middle attacks and certificate forgery. Values are `none`, `certificate`,
and `full`. Defaults to the value of `xpack.ssl.verification_mode`.

`ssl.supported_protocols`::
Supported protocols with versions. Defaults to the value of
`xpack.ssl.supported_protocols`.

`ssl.cipher_suites`
Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[
Java Cryptography Architecture documentation]. Defaults to the value of
`xpack.ssl.cipher_suites`.

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

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

`cache.hash_algo`::           
(Expert Setting) Specifies the hashing algorithm that will be used for 
the in-memory cached user credentials (see <<cache-hash-algo,Cache hash 
algorithms>> table for all possible values). Defaults to `ssha256`.

[[ref-pki-settings]]
[float]
==== PKI Realm Settings

`username_pattern`::        
The regular expression pattern used to extract the username from the 
certificate DN. The first match group is the used as the username. 
Defaults to `CN=(.*?)(?:,\|$)`

`certificate_authorities`::
List of PEM certificate files that should be used to authenticate a
user's certificate as trusted. Defaults to the trusted certificates configured for SSL.
This setting may not be used with `truststore.path`.

`truststore.path`::          
The path of a truststore to use. Defaults to the trusted certificates configured for SSL.
This setting may not be used with `certificate_authorities`.
 
`truststore.password`::    
The password for the truststore. Must be provided if `truststore.path` is set.

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

`files.role_mapping`::     
Specifies the <<security-files-location,location>> for the 
<<pki-role-mapping, YAML role  mapping configuration file>>.
Defaults to `CONFIG_DIR/x-pack/role_mapping.yml`.

[float]
[[ssl-tls-settings]]
=== Default TLS/SSL Settings
You can configure the following TLS/SSL settings in 
`elasticsearch.yml`. For more information, see
<<ssl-tls, Encrypting Communications>>. These settings will be used
for all of {xpack} unless they have been overridden by more specific
settings such as those for HTTP or Transport.

`xpack.ssl.supported_protocols`::
Supported protocols with versions. Valid protocols: `SSLv2Hello`,
`SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`. Defaults to `TLSv1.2`, `TLSv1.1`,
`TLSv1`.

`xpack.ssl.client_authentication`::
Controls the server's behavior in regard to requesting a certificate
from client connections. Valid values are `required`, `optional`, and `none`.
`required` forces a client to present a certificate, while `optional`
requests a client certificate but the client is not required to present one.
Defaults to `required`.

`xpack.ssl.verification_mode`::
Controls the verification of certificates. Valid values are `none`,
`certificate`, and `full`. Defaults to `full`.

`xpack.ssl.cipher_suites`
Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[
Java Cryptography Architecture documentation]. Defaults to `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`,
`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`,
`TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA`.

[float]
[[tls-ssl-key-settings]]
==== Default TLS/SSL Key and Trusted Certificate Settings

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

[float]
===== PEM Encoded Files

When using PEM encoded files, use the following settings:

`xpack.ssl.key`::
Path to the PEM encoded file containing the private key.

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

`xpack.ssl.certificate`::
Path to a PEM encoded file containing the certificate (or certificate chain)
that will be presented to clients when they connect.

`xpack.ssl.certificate_authorities`::
List of paths to the PEM encoded certificate files that should be trusted.

[float]
===== Java Keystore Files

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

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

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

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

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

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

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

include::ssl-settings.asciidoc[]

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

include::ssl-settings.asciidoc[]

[[ssl-tls-profile-settings]]
[float]
==== Transport Profile TLS/SSL Settings
The same settings that are available for the <<transport-tls-ssl-settings, default transport>>
are also available for each transport profile. By default, the settings for a
transport profile will be the same as the default transport unless they
are specified.

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

[float]
[[ip-filtering-settings]]
=== IP Filtering Settings
You can configure the following settings for <<ip-filtering, IP filtering>>.

`xpack.security.transport.filter.allow`::
List of IP addresses to allow.

`xpack.security.transport.filter.deny`::
List of IP addresses to deny.

`xpack.security.http.filter.allow`::
List of IP addresses to allow just for HTTP.

`xpack.security.http.filter.deny`::
List of IP addresses to deny just for HTTP.

`transport.profiles.$PROFILE.xpack.security.filter.allow`::
List of IP addresses to allow for this profile.

`transport.profiles.$PROFILE.xpack.security.filter.deny`::
List of IP addresses to deny for this profile.