From version 5.0 onward, Shield is part of X-Pack. For more information, see Securing the Elastic Stack.
« Getting Started (Long Version) Authentication »
Elastic Docs ›Shield - Elasticsearch Security Plugin [1.2]

Authorization

edit

Authorization

edit

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.

Roles, Permissions and Privileges

edit

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 logs-*.

As an administrator, you will need to define the roles that you want to use, then assign users to the roles.

The Role Definition File roles.yml

edit

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 with it.

The 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

A valid role name must be at least 1 character and no longer than 30 characters. It must begin with a letter (a-z) or an underscore (_). Subsequent characters can be letters, underscores (_), digits (0-9) or any of the following symbols @, - or $

The above example defines these roles:

admin

Has full access (all privileges) on the cluster and full access on all indices in the cluster.

power_user

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.

user

Cannot update or monitor the cluster. Has read-only access to all indices in the cluster.

events_user

Has read-only access to all indices with the events_ prefix.

See the complete list of available cluster and indices privileges.

Action Level Access Control

edit

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.

« Getting Started (Long Version) Authentication »