Managing Roles

You use the REST APIs to create, update, and delete roles. If you authenticate users with the native realm, you assign roles to users through the User Management APIs. If you use the Active Directory, LDAP, or PKI realms, you configure role mappings in a YAML file. To assign roles to users in the file realm, you use the esusers command-line tool.

As of 2.3.0 the REST APIs are the preferred way to manage roles. However, you can still configure file-based roles, which can be useful if you want to define roles that only an administrator with physical access to the nodes in a cluster can modify.

Adding Roles

edit

To add or modify a role, submit a PUT or POST request to the /_shield/role/<rolename> endpoint.

Role names 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 $.

In the role definition, you specify the cluster privileges and indices privileges the role grants. Optionally, you can also configure field and document level security and assign run_as privileges.

POST /_shield/role/my_admin_role
{
  "cluster": ["all"], 
  "indices": [ 
    {
      "names": [ "index1", "index2" ], 
      "privileges": ["all"], 
      "fields": [ "title", "body" ], 
      "query": "{\"match\": {\"title\": \"foo\"}}" 
    }
  ],
  "run_as": [ "other_user" ] 
}

	The cluster privileges that the role grants. Optional
	The indices privileges that the role grants. Optional
	The indices that the role applies to. Required for indices privileges.
	The indices privileges that the role grants. Required for indices privileges.
	The specific index fields that the role grants access to. Optional, defaults to all fields.
	A query that defines the documents that the role grants access to. Optional, defaults to all documents.
	The run-as privileges that the role grants. Allows users with this role to perform actions on behalf of the specified `other_user`. Optional

When updating a role, you need to specify the complete role definition, not just the fields you want to modify.

A successful call returns a JSON structure that shows whether the role has been created or updated.

{
  "role": {
    "created": true 
  }
}

When an existing role is updated, created is set to false.

Specifying Index Names in a Role

edit

Within the indices.names array, you can use wildcards and regular expressions to refer to multiple indices.

Wildcards - by default you can use simple wildcard matching where * is a placeholder for zero or more characters, ? is a placeholder for a single character and \ can be used as an escape character.
Regular Expressions - to match more complex patterns you can enable regular expressions by wrapping the pattern within a pair of forward slashes (/). Regular expressions are based on Lucene’s regexp automaton syntax. Any pattern starting with / and not ending with / is considered to be malformed.

Example Regular Expressions.

"foo-bar":               # match the literal `foo-bar`
"foo-*":                 # match anything beginning with "foo-"
"logstash-201?-*":       # ? matches any one character
"/.*-201[0-9]-.*/":      # use a regex to match anything containing 2010-2019
"/foo":                  # syntax error - missing final /

Retrieving Roles

edit

To retrieve all roles, submit a GET request to the /_shield/role endpoint:

GET /_shield/role

To retrieve particular roles, specify the roles as a comma-separated list:

GET /_shield/role/my_admin_role,log_admin_role

An array of roles is returned that contains the JSON representation of each role.

{
  "found" : true, 
  "roles" : [ {
    "name" : "my_admin_role",
    "cluster" : [ "all" ],
    "indices" : [ {
      "names" : [ "index1", "index2" ],
      "privileges" : [ "all" ],
      "fields" : [ "title", "body" ],
      "query" : "{\"match\": {\"title\": \"foo\"}}"
    } ],
    "run_as" : [ "other_user" ]
  },
  {
    "name" : "log_admin_role",
    "cluster" : [ "all" ],
    "indices" : [ {
      "names" : [ "logs-*" ],
      "privileges" : [ "all" ],
    } ]
  }]
}

If the specified role is not defined in the native realm, found is set to false.

Deleting Roles

edit

To delete a role, submit a DELETE request to the /_shield/role/<rolename> endpoint:

DELETE /_shield/role/my_admin_role

If the role is successfully deleted, the request returns {"found": true}. Otherwise, found is set to false.

{
  "found" : true
}

« Role-based Access Control File-based Roles »