[[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 <>. === 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 <>. 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 <> 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[]