From version 5.0 onward, Shield is part of X-Pack. For more information, see Securing the Elastic Stack.
« Shield Privileges Shield Files »
Elastic Docs ›Shield [2.3] ›Reference

Shield Settings

edit

Shield Settings

edit

The parameters listed in this section are configured in the config/elasticsearch.yml configuration file.

Anonymous Access Settings [1.1.0] Added in 1.1.0.

edit
Name Default Description

shield.authc.anonymous.username

_es_anonymous_user

The username/principal of the anonymous user. Optional.

shield.authc.anonymous.roles

-

The roles that will be associated with the anonymous user. This setting must be set to enable anonymous access.

shield.authc.anonymous.authz_exception

true

When true, a HTTP 403 response will be returned when the anonymous user does not have the appropriate privileges for the requested action. The user will not be prompted to provide credentials to access the requested resource. When set to false, a HTTP 401 will be returned allowing for credentials to be provided for a user with the appropriate privileges.

Document and Field Level Security Settings

edit
Name Default Description

shield.dls_fls.enabled

true

Set to false to disallow document and field level security to be configured in the roles.yml file.

Message Authentication Settings

edit
Name Default Description

shield.system_key.file

CONFIG_DIR/shield/system_key

Sets the location of the system_key file generated by running syskeygen tool from ES_HOME. Defaults to CONFIG_DIR/shield/system_key. The system key is used to secure node to node communications. You must use the same system key on each node in the cluster. You do not need to configure a system key for the Java Transport Client. (Using the Java Node Client with Shield is neither recommended or supported.)

Realm Settings

edit

All realms are configured under the shield.authc.realms settings, keyed by their names as follows:

shield.authc.realms:

    realm1:
        type: file
        order: 0
        ...

    realm2:
        type: ldap
        order: 1
        ...

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

Table 20. Common Settings to All Realms

Name Required Default Description

type

yes

-

The type of the realm (currently native, file, ldap, active_directory, or pki)

order

no

Integer.MAX_VALUE

The priority of the realm within the realm chain

enabled

no

true

Enable/disable the realm

Table 21. File Realm Settings

Name Required Default Description

files.users

no

CONFIG_DIR/shield/users

The location of the users file.

files.users_roles

no

CONFIG_DIR/shield/users_roles

The location of the users_roles file.

cache.ttl

no

20m

The time-to-live for cached user entries—​user credentials are cached for this configured period of time. Defaults to 20m. Specify values using the standard Elasticsearch time units.

cache.max_users

no

100000

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

cache.hash_algo

no

ssha256

(Expert Setting) The hashing algorithm that is used for the in-memory cached user credentials. See the Cache hash algorithms table for all possible values.

Table 22. LDAP Realm Settings

Name Required Default Description

url

yes

-

An LDAP URL in the format ldap[s]://<server>:<port>.

load_balance.type

no

failover

The behavior to use when there are multiple LDAP URLs defined. For supported values see LDAP load balancing and failover types.

load_balance.cache_ttl

no

1h

When using dns_failover or dns_round_robin as the load balancing type, this setting controls the amount of time to cache DNS lookups.

bind_dn

no

Empty

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.

bind_password

no

Empty

The password for the user that will be used to bind to the LDAP.

user_dn_templates

yes *

-

The DN template that replaces the user name with the string {0}. This element is multivalued, allowing for multiple user contexts.

user_group_attribute

no

memberOf

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.

user_search.base_dn

yes *

-

Specifies a container DN to search for users.

user_search.scope

no

sub_tree

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.

user_search.attribute

no

uid

The attribute to match with the username presented to Shield.

user_search.pool.size

no

20

The maximum number of connections to the LDAP server to allow in the connection pool.

user_search.pool.initial_size

no

5

The initial number of connections to create to the LDAP server on startup.

user_search.pool.health_check.enabled

no

true

Flag to enable or disable a health check on LDAP connections in the connection pool. Connections will be checked in the background at the specified interval.

user_search.pool.health_check.dn

no

Value of bind_dn

The distinguished name to be retrieved as part of the health check. If bind_dn is not specified, a value must be specified.

user_search.pool.health_check.interval

no

60s

The interval to perform background checks of connections in the pool.

group_search.base_dn

no

-

The container DN to search for groups in which the user has membership. When this element is absent, Shield searches for the attribute specified by user_group_attribute set on the user in order to determine group membership.

group_search.scope

no

sub_tree

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.

group_search.filter

no

See description

When not set, the realm will search for group, groupOfNames, or groupOfUniqueNames, with the attributes member or memberOf. Any instance of {0} in the filter will be replaced by the user attribute defined in group_search.user_attribute

group_search.user_attribute

no

Empty

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.

unmapped_groups_as_roles

no

false

Takes a boolean variable. When this element is set to true, the names of any unmapped LDAP groups are used as role names and assigned to the user. THe default value is false.

files.role_mapping

no

CONFIG_DIR/shield/role_mapping.yml

The location for the YAML role mapping configuration file.

follow_referrals

no

true

Boolean value that specifies whether Shield 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 (e.g. search).

timeout.tcp_connect

no

"5s" - for 5 seconds

The TCP connect timeout period for establishing an LDAP connection. An s at the end indicates seconds, or ms indicates milliseconds.

timeout.tcp_read

no

"5s" - for 5 seconds

The TCP read timeout period after establishing an LDAP connection. An s at the end indicates seconds, or ms indicates milliseconds.

timeout.ldap_search

no

"5s" - for 5 seconds

The LDAP Server enforced timeout period for an LDAP search. An s at the end indicates seconds, or ms indicates milliseconds.

hostname_verification

no

true

Performs hostname verification when using ldaps to protect against man in the middle attacks.

cache.ttl

no

20m

Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). (use the standard Elasticsearch time units).

cache.max_users

no

100000

Specified the maximum number of user entries that can live in the cache at a given time.

cache.hash_algo

no

ssha256

(Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see Cache hash algorithms table for all possible values).

user_dn_templates is required to operate in user template mode and user_search.base_dn is required to operated in user search mode. Only one is required for a given realm configuration. For more information on the different modes, see ldap realms.

Table 23. Active Directory Realm Settings

Name Required Default Description

url

no

ldap://<domain_name>:389

A URL in the format ldap[s]://<server>:<port> If not specified the URL will be derived from the domain_name, assuming clear-text ldap and port 389 (e.g. ldap://<domain_name>:389).

load_balance.type

no

failover

The behavior to use when there are multiple LDAP URLs defined. For supported values see LDAP load balancing and failover types.

load_balance.cache_ttl

no

1h

When using dns_failover or dns_round_robin as the load balancing type, this setting controls the amount of time to cache DNS lookups.

domain_name

yes

-

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.

unmapped_groups_as_roles

no

false

Takes a boolean variable. When this element is set to true, the names of any unmapped groups and the user’s relative distinguished name are used as role names and assigned to the user. THe default value is false.

files.role_mapping

no

CONFIG_DIR/shield/role_mapping.yml

The location for the YAML role mapping configuration file.

user_search.base_dn

no

Root of Active Directory

The context to search for a user. The default value for this element is the root of the Active Directory domain.

user_search.scope

no

sub_tree

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.

user_search.filter

no

See description

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

group_search.base_dn

no

Root of Active Directory

The context to search for groups in which the user has membership. The default value for this element is the root of the the Active Directory domain

group_search.scope

no

sub_tree

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.

timeout.tcp_connect

no

5s - for 5 seconds

The TCP connect timeout period for establishing an LDAP connection. An s at the end indicates seconds, or ms indicates milliseconds.

timeout.tcp_read

no

5s - for 5 seconds

The TCP read timeout period after establishing an LDAP connection. An s at the end indicates seconds, or ms indicates milliseconds.

timeout.ldap_search

no

5s - for 5 seconds

The LDAP Server enforced timeout period for an LDAP search. An s at the end indicates seconds, or ms indicates milliseconds.

hostname_verification

no

true

Performs hostname verification when using ldaps to protect against man in the middle attacks.

cache.ttl

no

20m

Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). (use the standard Elasticsearch time units).

cache.max_users

no

100000

Specified the maximum number of user entries that can live in the cache at a given time.

cache.hash_algo

no

ssha256

(Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see Cache hash algorithms table for all possible values).

Table 24. PKI Realm Settings

Name Required Default Description

username_pattern

no

CN=(.*?)(?:,|$)

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

truststore.path

no

shield.ssl.keystore

The path of a truststore to use. The default truststore is the one defined by SSL/TLS settings

truststore.password

no

-

The password to the truststore. Must be provided if truststore.path is set.

truststore.algorithm

no

SunX509

Algorithm for the trustsore. Default is SunX509

files.role_mapping

no

CONFIG_DIR/shield/role_mapping.yml

Specifies the location for the YAML role mapping configuration file.

Roles Settings

edit
Name Default Description

shield.authz.store.files.roles

CONFIG_DIR/shield/roles.yml

The location of the roles definition file.

TLS/SSL Settings

edit

Table 25. Shield TLS/SSL Settings

Name Default Description

shield.ssl.keystore.path

None

Absolute path to the keystore that holds the private keys

shield.ssl.keystore.password

None

Password to the keystore

shield.ssl.keystore.key_password

Same value as shield.ssl.keystore.password

Password for the private key in the keystore

shield.ssl.keystore.algorithm

SunX509

Format for the keystore

shield.ssl.truststore.path

shield.ssl.keystore.path

If not set, this setting defaults to shield.ssl.keystore

shield.ssl.truststore.password

shield.ssl.keystore.password

Password to the truststore

shield.ssl.truststore.algorithm

SunX509

Format for the truststore

shield.ssl.protocol

TLSv1.2

Protocol for security: SSL, SSLv2, SSLv3, TLS, TLSv1, TLSv1.1, TLSv1.2

shield.ssl.supported_protocols

TLSv1, TLSv1.1, TLSv1.2

Supported protocols with versions. Valid protocols: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2

shield.ssl.ciphers

TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Cipher suites using key lengths greater than 128 bits require the JCE Unlimited Strength Jurisdiction Policy Files.

shield.ssl.hostname_verification

true

Performs hostname verification on transport connections. This is enabled by default to protect against man in the middle attacks.

shield.ssl.hostname_verification.resolve_name

true

A reverse DNS lookup is necessary to find the hostname when connecting to a node via an IP Address. If this is disabled and IP addresses are used to connect to a node, the IP address must be specified as a SubjectAlternativeName when creating the certificate or hostname verification will fail. IP addresses will be used to connect to a node if they are used in following settings: network.host, network.publish_host, transport.publish_host, transport.profiles.$PROFILE.publish_host, discovery.zen.ping.unicast.hosts

shield.ssl.session.cache_size

1000

Number of SSL Sessions to cache in order to support session resumption. Setting the value to 0 means there is no size limit.

shield.ssl.session.cache_timeout

24h

The time after the creation of a SSL session before it times out. (uses the standard Elasticsearch time units).

shield.transport.ssl

false

Set this parameter to true to enable SSL/TLS

shield.transport.ssl.client.auth

required

Require client side certificates for transport protocol. Valid values are required, optional, and no. required forces a client to present a certificate, while optional requests a client certificate but the client is not required to present one.

shield.transport.filter.allow

None

List of IP addresses to allow

shield.transport.filter.deny

None

List of IP addresses to deny

shield.http.ssl

false

Set this parameter to true to enable SSL/TLS

shield.http.ssl.client.auth

no

Require client side certificates for HTTP. Valid values are required, optional, and no. required forces a client to present a certificate, while optional requests a client certificate but the client is not required to present one.

shield.http.filter.allow

None

List of IP addresses to allow just for HTTP

shield.http.filter.deny

None

List of IP addresses to deny just for HTTP

Table 26. Shield TLS/SSL settings per profile

Name Default Description

transport.profiles.$PROFILE.shield.ssl

Same as shield.transport.ssl

Setting this parameter to true will enable SSL/TLS for this profile; false will disable SSL/TLS for this profile.

transport.profiles.$PROFILE.shield.truststore.path

None

Absolute path to the truststore of this profile

transport.profiles.$PROFILE.shield.truststore.password

None

Password to the truststore

transport.profiles.$PROFILE.shield.truststore.algorithm

SunX509

Format for the truststore

transport.profiles.$PROFILE.shield.keystore.path

None

Absolute path to the keystore of this profile

transport.profiles.$PROFILE.shield.keystore.password

None

Password to the keystore

transport.profiles.$PROFILE.shield.keystore.key_password

Same value as transport.profiles.$PROFILE.shield.keystore.password

Password for the private key in the keystore

transport.profiles.$PROFILE.shield.keystore.algorithm

SunX509

Format for the keystore

transport.profiles.$PROFILE.shield.session.cache_size

1000

Number of SSL Sessions to cache in order to support session resumption. Setting the value to 0 means there is no size limit.

transport.profiles.$PROFILE.shield.session.cache_timeout

24h

The time after the creation of a SSL session before it times out. (uses the standard Elasticsearch time units).

transport.profiles.$PROFILE.shield.filter.allow

None

List of IP addresses to allow for this profile

transport.profiles.$PROFILE.shield.filter.deny

None

List of IP addresses to deny for this profile

transport.profiles.$PROFILE.shield.ssl.client.auth

required

Require client side certificates. Valid values are required, optional, and no. required forces a client to present a certificate, while optional requests a client certificate but the client is not required to present one.

transport.profiles.$PROFILE.shield.type

node

Defines allowed actions on this profile, allowed values: node and client

transport.profiles.$PROFILE.shield.ciphers

TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

Supported cipher suites can be found in Oracle’s Java Cryptography Architecture documentation. Cipher suites using key lengths greater than 128 bits require the JCE Unlimited Strength Jurisdiction Policy Files.

transport.profiles.$PROFILE.shield.protocol

TLSv1.2

Protocol for security: SSL, SSLv2, SSLv3, TLS, TLSv1, TLSv1.1, TLSv1.2

transport.profiles.$PROFILE.shield.supported_protocols

TLSv1, TLSv1.1, TLSv1.2

Supported protocols with versions. Valid protocols: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2
« Shield Privileges Shield Files »