From version 5.0 onward, Shield is part of X-Pack. For more information, see Securing the Elastic Stack.

« Example Shield Deployments Limitations »

›

Reference

edit

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

Run As

edit

The run_as permission enables an authenticated user to submit requests on behalf of another user. The value can be a user name or a comma-separated list of user names. (You can also specify users as an array of strings or a YAML sequence.) For more information, see Submitting Requests on Behalf of Other Users.

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/render/template/search
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/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. For example, having one user define a template that matches another user’s index.

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/get
indices:admin/exists
indices:admin/flush
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/template/delete
indices:admin/template/get
indices:admin/template/put
indices:admin/types/exists
indices:admin/upgrade
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/shard_stores
indices:monitor/stats
indices:monitor/upgrade
indices:data/read/count
indices:data/read/exists
indices:data/read/explain
indices:data/read/field_stats
indices:data/read/get
indices:data/read/mget
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/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 19. Shield Message Authentication Settings

Name	Default	Description
`shield.system_key.file`	`CONFIG_DIR/shield/system_key`	Sets the location of the `system_key` file. For more information, see Enabling Message Authentication.

Table 20. Shield Anonymous Access Settings [1.1.0] Added in 1.1.0.

Name	Default	Description
`shield.authc.anonymous.username`	`_es_anonymous_user`	The username/principal of the anonymous user (this setting is 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 permissions 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 permissions.

Table 21. Shield Document and Field Level Security Settings

Name	Default	Description
`shield.dls_fls.enabled`	`false`	Set to `true` to enable document and field level security. You cannot submit `_bulk` update requests when document and field level security is enabled.

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 22. 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 23. esusers Realm

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

Name	Required	Default	Description
`url`	yes	-	An LDAP URL in the format `ldap[s]://<server>:<port>`.
`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/users/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 25. 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 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/users/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 26. Shield PKI 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/users/role_mapping.yml`	Specifies the location for the YAML role mapping configuration file.

Table 27. Cache hash algorithms

Algorithm	Description
`ssha256`	Uses a salted `SHA-256` algorithm (default).
`md5`	Uses `MD5` algorithm.
`sha1`	Uses `SHA1` algorithm.
`bcrypt`	Uses `bcrypt` algorithm with salt generated in 10 rounds.
`bcrypt4`	Uses `bcrypt` algorithm with salt generated in 4 rounds.
`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.
`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 28. Shield Roles Settings

Name	Default	Description
`shield.authz.store.file.roles`	`CONFIG_DIR/shield/users/roles.yml`	The location of the roles definition file.

TLS/SSL Settings

edit

Table 29. 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 30. 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`

Files used by Shield

edit

The Shield security plugin uses the following files:

CONFIG_DIR/shield/roles.yml defines the roles in use on the cluster (read more here).
CONFIG_DIR/shield/users defines the hashed passwords for users on the cluster (read more here).
CONFIG_DIR/shield/users_roles defines the role assignments for users on the cluster (read more here).
CONFIG_DIR/shield/role_mapping.yml defines the role assignments for a Distinguished Name (DN) to a role. This allows for LDAP and Active Directory groups and users and PKI users to be mapped to roles (read more here).
CONFIG_DIR/shield/logging.yml contains audit information (read more here).
CONFIG_DIR/shield/system_key holds a cluster secret key used for message authentication. For more information, see Enabling Message Authentication.

Any files that Shield uses must be stored in the Elasticsearch configuration directory. Elasticsearch runs with restricted permissions and is only permitted to read from the locations configured in the directory layout for enhanced security.

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.

« Example Shield Deployments Limitations »