From version 5.0 onward, Shield is part of X-Pack. For more information, see Securing the Elastic Stack.
« Appendix 7. Trouble Shooting Appendix 9. Release Notes »
Elastic Docs ›Shield - Elasticsearch Security Plugin [1.0]

Appendix 8. Reference

edit

Appendix 8. Reference

edit

Privileges

edit

Cluster

edit

all

All cluster administration operations, like snapshotting, node shutdown/restart, settings update or rerouting

monitor

All cluster read-ony operations, like cluster health & state, hot threads, node info, node & cluster stats, snapshot/restore status, pending cluster tasks

manage_shield

All Shield related operations (currently only exposing an API for clearing the realm caches)

Indices

edit

all

Any action on an index

manage

All monitor privileges plus index administration (aliases, analyze, cache clear, close, delete, exists, flush, mapping, open, optimize, refresh, settings, search shards, templates, validate, warmers) monitor": All actions, that are required for monitoring and read-only (recovery, segments info, index stats & status)

data_access

A shortcut of all of the below privileges

crud

A shortcut of read and write privileges

read

Read only access to actions (count, explain, get, exists, mget, get indexed scripts, more like this, multi percolate/search/termvector), percolate, scroll, clear_scroll, search, suggest, tv)

search

All of suggest and executing an arbitrary search request (including multi-search API)

get

Allow to execute a GET request for a single document or multiple documents via the multi-get API

suggest

Allow to execute the _suggest API

index

Privilege to index and update documents

create_index

Privilege to create an index. A create index request may contain aliases to be added to the index once created. In that case the request requires manage_aliases privilege as well, on both the index and the aliases names.

manage_aliases

Privilege to add and remove aliases, as well as retrieve aliases information. Note that in order to add an alias to an existing index, the manage_aliases privilege is required on the existing index as well as on the alias name

delete

Privilege to delete documents (includes delete by query)

write

Privilege to index, update, delete, delete by query and bulk operations on documents, in addition to delete and put indexed scripts

Action level privileges

edit

Although rarely needed, it is also possible to define privileges on specific actions that are available in Elasticsearch. This only applies to publicly available indices and cluster actions.

Cluster actions privileges
edit
  • cluster:admin/nodes/restart
  • cluster:admin/nodes/shutdown
  • cluster:admin/repository/delete
  • cluster:admin/repository/get
  • cluster:admin/repository/put
  • cluster:admin/repository/verify
  • cluster:admin/reroute
  • cluster:admin/settings/update
  • cluster:admin/snapshot/create
  • cluster:admin/snapshot/delete
  • cluster:admin/snapshot/get
  • cluster:admin/snapshot/restore
  • cluster:admin/snapshot/status
  • cluster:admin/plugin/license/get
  • cluster:admin/plugin/license/delete
  • cluster:admin/plugin/license/put
  • cluster:admin/indices/scroll/clear_all
  • cluster:admin/analyze
  • cluster:admin/shield/realm/cache/clear
  • cluster:monitor/health
  • cluster:monitor/nodes/hot_threads
  • cluster:monitor/nodes/info
  • cluster:monitor/nodes/stats
  • cluster:monitor/state
  • cluster:monitor/stats
  • cluster:monitor/task
  • indices:admin/template/delete
  • indices:admin/template/get
  • indices:admin/template/put

While indices template actions typically relate to indices, they are categorized under cluster actions to avoid potential security leaks (e.g. having one user define a template that may match another user’s index and then be applied).

Indices actions privileges
edit
  • indices:admin/aliases
  • indices:admin/aliases/exists
  • indices:admin/aliases/get
  • indices:admin/analyze
  • indices:admin/cache/clear
  • indices:admin/close
  • indices:admin/create
  • indices:admin/delete
  • indices:admin/exists
  • indices:admin/flush
  • indices:admin/get
  • indices:admin/mapping/delete
  • indices:admin/mapping/put
  • indices:admin/mappings/fields/get
  • indices:admin/mappings/get
  • indices:admin/open
  • indices:admin/optimize
  • indices:admin/refresh
  • indices:admin/settings/update
  • indices:admin/shards/search_shards
  • indices:admin/types/exists
  • indices:admin/validate/query
  • indices:admin/warmers/delete
  • indices:admin/warmers/get
  • indices:admin/warmers/put
  • indices:monitor/recovery
  • indices:monitor/segments
  • indices:monitor/settings/get
  • indices:monitor/stats
  • indices:monitor/status
  • indices:data/read/count
  • indices:data/read/exists
  • indices:data/read/explain
  • indices:data/read/get
  • indices:data/read/mget
  • indices:data/read/mlt
  • indices:data/read/mpercolate
  • indices:data/read/msearch
  • indices:data/read/mtv
  • indices:data/read/percolate
  • indices:data/read/script/get
  • indices:data/read/scroll
  • indices:data/read/scroll/clear
  • indices:data/read/search
  • indices:data/read/suggest
  • indices:data/read/tv
  • indices:data/write/bulk
  • indices:data/write/delete
  • indices:data/write/delete/by_query
  • indices:data/write/index
  • indices:data/write/script/delete
  • indices:data/write/script/put
  • indices:data/write/update

Shield Settings

edit

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

Table 18. Shield Message Authentication Settings

Name Default Description

shield.system_key.file

system_key under Shield’s config

Sets the location of the system_key file (read more here)

Realm Settings

edit

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

shield.authc.realms:

    realm1:
        type: esusers
        order: 0
        ...

    realm2:
        type: ldap
        order: 1
        ...

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

Table 19. Common Settings to All Realms

Name Required Default Description

type

yes

-

The type of the reamlm (currently esusers, ldap or active_directory)

order

no

Integer.MAX_VALUE

The priority of the realm within the realm chain

enabled

no

true

Enable/disable the realm

Table 20. esusers Realm

Name Required Default Description

files.users

no

users under Shield’s config

The location of users file

files.users_roles

no

users_roles under Shield’s config

The location of users_roles file

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). Defaults to 20m (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. Defaults to 100,000.

cache.hash_algo

no

bcrypt4

(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 21. Shield LDAP Settings

Name Required Default Description

url

yes

-

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

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.

group_search.base_dn

no

-

Specifies a container DN to search for groups in which the user has membership. When this element and all other elements beginning with group_search are absent, Shield searches for a memberOf attribute set on the user in order to determine group membership. If any of the group_search settings are set, this value must be provided.

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

role_mapping.yml under Shield’s config

The path and file name for the YAML role mapping configuration file. The default file name is role_mapping.yml in the Shield config directory.

connect_timeout

no

"5s" - for 5 seconds

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

read_timeout

no

"5s" - for 5 seconds

The timeout period for an LDAP operation. 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

bcrypt4

(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 22. Shield Active Directory 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).

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 are used as role names and assigned to the user. THe default value is false.

files.role_mapping

no

role_mapping.yml under Shield’s config

The path and file name for the YAML role mapping configuration file. The default file name is role_mapping.yml in the Shield config directory.

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

bcrypt4

(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 23. Cache hash algorithms

Algorithm

Description

bcrypt

Uses bcrypt algorithm with salt generated in 10 rounds.

bcrypt4

Uses bcrypt algorithm with salt generated in 4 rounds (default).

bcrypt5

Uses bcrypt algorithm with salt generated in 5 rounds.

bcrypt6

Uses bcrypt algorithm with salt generated in 6 rounds.

bcrypt7

Uses bcrypt algorithm with salt generated in 7 rounds.

bcrypt8

Uses bcrypt algorithm with salt generated in 8 rounds.

bcrypt9

Uses bcrypt algorithm with salt generated in 9 rounds.

sha1

Uses SHA1 algorithm.

sha2

Uses SHA2 algorithm.

md5

Uses MD5 algorithm.

noop,clear_text

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 (e.g. memory dumps and ptrace).

Table 24. Shield Roles Settings

Name Default Description

shield.authz.store.file.roles

roles.yml under Shield’s config

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

TLS

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_DHE_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

true

Require client side certificates for transport protocol

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

false

Require client side certificates for HTTP

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

true

Require client side certificates

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_DHE_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.supported_protocols

TLSv1, TLSv1.1, TLSv1.2

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

Files used by Shield

edit

The Shield security plugin uses the following files:

  • config/shield/roles.yml defines the roles in use on the cluster (read more here).
  • config/shield/users defines the hashed passwords for users on the cluster (read more here).
  • config/shield/users_roles defines the role assignments for users on the cluster (read more here).
  • config/shield/role_mapping.yml defines the role assignments for LDAP or Active Directory groups (read more here).
  • config/shield/logging.yml contains audit information (read more here).
  • config/shield/system_key holds a cluster secret key used for message authentication (read more here).

Several of these files are in the YAML format. When you edit these files, be aware that YAML is indentation-level sensitive and indentation errors can lead to configuration errors. Avoid the tab character to set indentation levels, or use an editor that automatically expands tabs to spaces.

Be careful to properly escape YAML constructs such as : or leading exclamation points within quoted strings. Using the | or > characters to define block literals instead of escaping the problematic characters can help avoid problems.

« Appendix 7. Trouble Shooting Appendix 9. Release Notes »