OpenSearch/shield/docs/public/configuring-rbac.asciidoc

[[configuring-rbac]]
== Configuring Role-based Access Control

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]]
[float]
=== Roles, Permissions and Privileges

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.

[[defining-roles]]
=== Defining Roles
Roles are defined in the role definition file `roles.yml` located in `CONFIG_DIR/shield`.
This is a YAML file where each entry defines the unique role name and the cluster and indices permissions associated
with it.

[IMPORTANT]
==============================
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:

[source,yaml]
-----------------------------------
# All cluster rights
# All operations on all indices
admin:
  cluster: all
  indices:
    '*':
      privileges: all

# Monitoring cluster privileges
# All operations on all indices
power_user:
  cluster: monitor
  indices:
    '*':
      privileges: all

# Only read operations on indices
user:
  indices:
    '*':
      privileges: read

# Only read operations on indices named events_*
events_user:
  indices:
    'events_*':
      privileges: read
-----------------------------------

[[valid-role-name]]
NOTE: 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 <<privileges-list, cluster and indices privileges>>.


=== Granting Privileges for Specific Actions

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
[source,yaml]
---------------------------------------------------
# Only GET read action on index named events_index
get_user:
  indices:
    'events_index':
      privileges: 'indices:data/read/get'
---------------------------------------------------

See the complete list of available <<ref-actions-list, cluster and indices actions>>.

TIP: 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
[source,yaml]
------------------------------------------------------------------------------------
"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 /
------------------------------------------------------------------------------------

TIP: Once the roles are defined, users can then be associated with any number of these roles. In  
<<setting-up-authentication,Setting Up Authentication>> we'll learn more about authentication and see how users can be associated with the 
configured roles.

The privileges can also directly be set on an index expression. This notation is useful if no other security features
are configured.

.Shorter privileges notation
[source,yaml]
---------------------------------------------------
# Only GET read action on index named events_index
get_user:
  indices:
    'events_index': 'indices:data/read/get'
---------------------------------------------------

include::granting-alias-privileges.asciidoc[]

include::mapping-roles.asciidoc[]

include::setting-up-field-and-document-level-security.asciidoc[]

include::submitting-requests-for-other-users.asciidoc[]