Managing Roles
editManaging Roles
editYou 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
editTo 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 |
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.
Specifying Index Names in a Role
editWithin 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
editTo 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" ], } ] }] }
Deleting Roles
editTo 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 }