Appendix 8. Reference
editAppendix 8. Reference
editPrivileges
editCluster
edit
|
All cluster administration operations, like snapshotting, node shutdown/restart, settings update or rerouting |
|
All cluster read-ony operations, like cluster health & state, hot threads, node info, node & cluster stats, snapshot/restore status, pending cluster tasks |
|
All Shield related operations (currently only exposing an API for clearing the realm caches) |
Indices
edit
|
Any action on an index |
|
All |
|
A shortcut of all of the below privileges |
|
A shortcut of |
|
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) |
|
All of |
|
Allow to execute a GET request for a single document or multiple documents via the multi-get API |
|
Allow to execute the |
|
Privilege to index and update documents |
|
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 |
|
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 |
|
Privilege to delete documents (includes delete by query) |
|
Privilege to index, update, delete, delete by query and bulk operations on documents, in addition to delete and put indexed scripts |
Action level privileges
editAlthough 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
editThe parameters listed in this section are configured in the config/elasticsearch.yml
configuration file.
Table 21. Shield Anonymous Access Settings [1.1.0] Added in 1.1.0.
Name | Default | Description |
---|---|---|
|
|
The username/principal of the anonymous user (this setting is optional) |
|
- |
The roles that will be associated with the anonymous user. This setting must be set to enable anonymous access. |
Realm Settings
editAll 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 |
---|---|---|---|
|
yes |
- |
The type of the reamlm (currently |
|
no |
Integer.MAX_VALUE |
The priority of the realm within the realm chain |
|
no |
true |
Enable/disable the realm |
Table 23. esusers Realm
Name | Required | Default | Description |
---|---|---|---|
|
no |
|
The location of users file |
|
no |
|
The location of users_roles file |
|
no |
|
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 |
|
no |
100000 |
Specified the maximum number of user entries that can live in the cache at a given time. Defaults to 100,000. |
|
no |
|
(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. Shield LDAP Settings
Name | Required | Default | Description |
---|---|---|---|
|
yes |
- |
An LDAP URL in the format |
|
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. |
|
no |
Empty |
The password for the user that will be used to bind to the LDAP. |
|
yes * |
- |
The DN template that replaces the user name with the string |
|
yes * |
- |
Specifies a container DN to search for users. |
|
no |
|
The scope of the user search. Valid values are |
|
no |
|
The attribute to match with the username presented to Shield. |
|
no |
|
The maximum number of connections to the LDAP server to allow in the connection pool. |
|
no |
|
The initial number of connections to create to the LDAP server on startup. |
|
no |
|
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. |
|
no |
Value of |
The distinguished name to be retrieved as part of the health check. If |
|
no |
|
The interval to perform background checks of connections in the pool. |
|
yes |
- |
The container DN to search for groups in which the user has membership. When this element is absent, Shield searches for a |
|
no |
|
Specifies whether the group search should be |
|
no |
See description |
When not set, the realm will search for |
|
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. |
|
no |
false |
Takes a boolean variable. When this element is set to |
|
no |
|
The path and file name for the YAML role mapping configuration file. The default file name is |
|
no |
|
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). |
|
no |
"5s" - for 5 seconds |
The timeout period for establishing an LDAP connection. An |
|
no |
"5s" - for 5 seconds |
The timeout period for an LDAP operation. An |
|
no |
true |
Performs hostname verification when using |
|
no |
|
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). |
|
no |
100000 |
Specified the maximum number of user entries that can live in the cache at a given time. |
|
no |
|
(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 |
---|---|---|---|
|
no |
|
A URL in the format |
|
yes |
- |
The domain name of Active Directory. The cluster can derive the URL and |
|
no |
false |
Takes a boolean variable. When this element is set to |
|
no |
|
The path and file name for the YAML role mapping configuration file. The default file name is |
|
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. |
|
no |
|
Specifies whether the user search should be |
|
no |
See description |
Specifies a filter to use to lookup a user given a username. The default filter looks up |
|
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 |
|
no |
|
Specifies whether the group search should be |
|
no |
|
The TCP connect timeout period for establishing an LDAP connection. An |
|
no |
|
The TCP read timeout period after establishing an LDAP connection. An |
|
no |
|
The LDAP Server enforced timeout period for an LDAP search. An |
|
no |
true |
Performs hostname verification when using |
|
no |
|
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). |
|
no |
100000 |
Specified the maximum number of user entries that can live in the cache at a given time. |
|
no |
|
(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. Cache hash algorithms
Algorithm |
Description |
|
Uses a salted |
|
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 (e.g. memory dumps and |
Table 27. Shield Roles Settings
Name | Default | Description |
---|---|---|
|
|
The location of the roles definition file |
TLS/SSL Settings
editTable 28. Shield TLS/SSL Settings
Name | Default | Description |
---|---|---|
|
None |
Absolute path to the keystore that holds the private keys |
|
None |
Password to the keystore |
|
Same value as |
Password for the private key in the keystore |
|
SunX509 |
Format for the keystore |
|
|
If not set, this setting defaults to |
|
|
Password to the truststore |
|
SunX509 |
Format for the truststore |
|
|
Protocol for security: |
|
|
Supported protocols with versions. Valid protocols: |
|
|
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. |
|
|
Performs hostname verification on transport connections. This is enabled by default to protect against man in the middle attacks. |
|
|
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 |
|
|
Number of SSL Sessions to cache in order to support session resumption. Setting the value to |
|
|
The time after the creation of a SSL session before it times out. (uses the standard elasticsearch time units). |
|
|
Set this parameter to |
|
|
Require client side certificates for transport protocol |
|
None |
List of IP addresses to allow |
|
None |
List of IP addresses to deny |
|
|
Set this parameter to |
|
|
Require client side certificates for HTTP |
|
None |
List of IP addresses to allow just for HTTP |
|
None |
List of IP addresses to deny just for HTTP |
Table 29. Shield TLS/SSL settings per profile
Name | Default | Description |
---|---|---|
|
Same as |
Setting this parameter to true will enable SSL/TLS for this profile; false will disable SSL/TLS for this profile. |
|
None |
Absolute path to the truststore of this profile |
|
None |
Password to the truststore |
|
SunX509 |
Format for the truststore |
|
None |
Absolute path to the keystore of this profile |
|
None |
Password to the keystore |
|
Same value as |
Password for the private key in the keystore |
|
SunX509 |
Format for the keystore |
|
|
Number of SSL Sessions to cache in order to support session resumption. Setting the value to |
|
|
The time after the creation of a SSL session before it times out. (uses the standard elasticsearch time units). |
|
None |
List of IP addresses to allow for this profile |
|
None |
List of IP addresses to deny for this profile |
|
|
Require client side certificates |
|
|
Defines allowed actions on this profile, allowed values: |
|
|
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. |
|
|
Protocol for security: |
|
|
Supported protocols with versions. Valid protocols: |
Files used by Shield
editThe 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.