136 lines
6.0 KiB
Plaintext
136 lines
6.0 KiB
Plaintext
[[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:
|
|
'*': 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
|
|
-----------------------------------
|
|
|
|
[[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': '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.
|
|
|
|
include::granting-alias-privileges.asciidoc[]
|
|
|
|
include::mapping-roles.asciidoc[]
|
|
|
|
include::setting-up-field-and-document-level-security.asciidoc[] |