Shield introduces the concept of action authorization to Elasticsearch. Action authorization restricts the actions users can execute on the cluster. Shield implements authorization as Role Based Access Control (RBAC), where all actions are restricted by default. Users are associated with roles that define a set of actions that are allowed for those users.
Privileges are actions or a set of actions that users may execute in Elasticsearch. For example, the ability to run a query is a privilege.
A permission is a set of privileges associated with one or more secured objects. For example, a permission could allow
querying or reading all documents of index
i1. There are two types of secured objects in Elasticsearch -
cluster and indices. Cluster permissions grant access to cluster-wide administrative and monitoring actions. Index
permissions grant data access, including administrative and monitoring actions on specific indices in the cluster.
A role is a named set of permissions. For example, you could define a role as a logging administrator. The logging
administrator is allowed to take all actions on indices named
As an administrator, you will need to define the roles that you want to use, then assign users to the roles.
Roles are defined in the role definition file
roles.yml located under Shield’s config directory.
This is a YAML file where each entry defines the unique role name and the cluster and indices permissions associated
roles.yml file is managed locally by the node and is not managed globally by the cluster. This means that
with a typical multi-node cluster, the exact same changes need to be applied on each and every node in the cluster.
A safer approach would be to apply the change on one of the nodes and have the
roles.yml distributed/copied to
all other nodes in the cluster (either manually or using a configuration management system such as Puppet or Chef).
The following snippet shows an example configuration:
# All cluster rights # All operations on all indices admin: cluster: all indices: '*': all # Monitoring cluster privileges # All operations on all indices power_user: cluster: monitor indices: '*': all # Only read operations on indices user: indices: '*': read # Only read operations on indices named events_* events_user: indices: 'events_*': read
The above example defines these roles:
Has full access (all privileges) on the cluster and full access on all indices in the cluster.
Has monitoring-only access on the cluster, enabling the user to request cluster metrics, information, and settings, without the ability to update settings. This user also has full access on all indices in the cluster.
Cannot update or monitor the cluster. Has read-only access to all indices in the cluster.
Has read-only access to all indices with the
See the complete list of available cluster and indices privileges.
The Shield security plugin enables access to specific actions in Elasticsearch. Access control using specific actions provides a finer level of granularity than roles based on named privileges.
The role in the following example allows access to document
GET actions for a specific index and nothing else:
Example Role Using Action-level Access Control.
# Only GET read action on index named events_index get_user: indices: 'events_index': 'indices:data/read/get'
See the complete list of available cluster and indices actions.
When specifying index names, you can use indices and aliases with their full names or regular expressions that refer to multiple indices.
- Wildcard (default) - simple wildcard matching where
*is a placeholder for zero or more characters,
?is a placeholder for a single character and
\may be used as an escape character.
- Regular Expressions - A more powerful syntax for matching more complex patterns. This regular expression is based on
Lucene’s regexp automaton syntax. To enable this syntax, it must be wrapped within a pair of forward slashes (
/). Any pattern starting with
/and not ending with
/is considered to be malformed.
Example Regular Expressions.
"foo-bar": all # match the literal `foo-bar` "foo-*": all # match anything beginning with "foo-" "logstash-201?-*": all # ? matches any one character "/.*-201[0-9]-.*/": all # use a regex to match anything containing 2010-2019 "/foo": all # syntax error - missing final /
Once the roles are defined, users can then be associated with any number of these roles. In the next section we’ll learn more about authentication and see how users can be associated with the configured roles.