File-based Roles

In most cases, roles should be managed through the REST APIs. However, roles defined in the roles.yml file located in CONFIG_DIR/shield can be used in conjunction with the file realm. This is a YAML file where each entry defines the unique role name and the cluster and index privileges 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 example configures four 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.

# All cluster rights
# All operations on all indices
admin:
  cluster:
    - all
  indices:
    - names: '*'
      privileges:
        - all

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

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

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

See Privileges for the complete list of cluster and indices privileges you can assign in a role.

Deprecated Role Formats

edit

Deprecated in 2.3.0.

The role format previously allowed the index expression to be set as a key for a set of privileges as seen below, but this has been deprecated in favor of using the names and privileges fields.

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.

# shorter privilege notation using index name as key and privilege as value
get_user:
  indices:
    'events_index': read

Index expression key notation.

# this notation uses the index name as the key with privileges as a value within the object
get_user:
  indices:
    'events_index':
      privileges: read

The updated way to define these roles is:

Collection notation.

# this notation uses collections equivalent to the above examples
get_user:
  indices:
    - names:
        - events_index
      privileges:
        - read

An extended example that shows cluster privileges and multiple index privileges in a role:

get_user:
  cluster:
    - monitor
  indices:
    - names:
        - events_index
      privileges:
        - read
    - names:
        - get_user_index
      privileges:
        - monitor
        - index
        - read

« Managing Roles Granting Privileges for Index Aliases »