|
@@ -1,205 +1,9 @@
|
|
|
-[role="xpack"]
|
|
|
+[float]
|
|
|
[[security-api-roles]]
|
|
|
-=== Role Management APIs
|
|
|
+=== Roles
|
|
|
|
|
|
-The Roles API enables you to add, remove, and retrieve roles in the `native`
|
|
|
-realm.
|
|
|
+You can use the following APIs to add, remove, and retrieve roles in the native realm:
|
|
|
|
|
|
-==== Request
|
|
|
-
|
|
|
-`GET /_xpack/security/role` +
|
|
|
-
|
|
|
-`GET /_xpack/security/role/<name>` +
|
|
|
-
|
|
|
-`DELETE /_xpack/security/role/<name>` +
|
|
|
-
|
|
|
-`POST /_xpack/security/role/<name>/_clear_cache` +
|
|
|
-
|
|
|
-`POST /_xpack/security/role/<name>` +
|
|
|
-
|
|
|
-`PUT /_xpack/security/role/<name>`
|
|
|
-
|
|
|
-
|
|
|
-==== Description
|
|
|
-
|
|
|
-The Roles API is generally the preferred way to manage roles, rather than using
|
|
|
-file-based role management. For more information, see
|
|
|
-{xpack-ref}/authorization.html[Configuring Role-based Access Control].
|
|
|
-
|
|
|
-
|
|
|
-==== Path Parameters
|
|
|
-
|
|
|
-`name`::
|
|
|
- (string) The name of the role. If you do not specify this parameter, the
|
|
|
- Get Roles API returns information about all roles.
|
|
|
-
|
|
|
-
|
|
|
-==== Request Body
|
|
|
-
|
|
|
-The following parameters can be specified in the body of a PUT or POST request
|
|
|
-and pertain to adding a role:
|
|
|
-
|
|
|
-`cluster`:: (list) A list of cluster privileges. These privileges define the
|
|
|
-cluster level actions that users with this role are able to execute.
|
|
|
-
|
|
|
-`indices`:: (list) A list of indices permissions entries.
|
|
|
-`field_security`::: (list) The document fields that the owners of the role have
|
|
|
-read access to. For more information, see
|
|
|
-{xpack-ref}/field-and-document-access-control.html[Setting Up Field and Document Level Security].
|
|
|
-`names` (required)::: (list) A list of indices (or index name patterns) to which the
|
|
|
-permissions in this entry apply.
|
|
|
-`privileges`(required)::: (list) The index level privileges that the owners of the role
|
|
|
-have on the specified indices.
|
|
|
-`query`::: A search query that defines the documents the owners of the role have
|
|
|
-read access to. A document within the specified indices must match this query in
|
|
|
-order for it to be accessible by the owners of the role.
|
|
|
-
|
|
|
-`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys
|
|
|
-that begin with `_` are reserved for system usage.
|
|
|
-
|
|
|
-`run_as`:: (list) A list of users that the owners of this role can impersonate.
|
|
|
-For more information, see
|
|
|
-{xpack-ref}/run-as-privilege.html[Submitting Requests on Behalf of Other Users].
|
|
|
-
|
|
|
-For more information, see {xpack-ref}/defining-roles.html[Defining Roles].
|
|
|
-
|
|
|
-
|
|
|
-==== Authorization
|
|
|
-
|
|
|
-To use this API, you must have at least the `manage_security` cluster
|
|
|
-privilege.
|
|
|
-
|
|
|
-
|
|
|
-==== Examples
|
|
|
-
|
|
|
-[[security-api-put-role]]
|
|
|
-To add a role, submit a PUT or POST request to the `/_xpack/security/role/<rolename>`
|
|
|
-endpoint:
|
|
|
-
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-POST /_xpack/security/role/my_admin_role
|
|
|
-{
|
|
|
- "cluster": ["all"],
|
|
|
- "indices": [
|
|
|
- {
|
|
|
- "names": [ "index1", "index2" ],
|
|
|
- "privileges": ["all"],
|
|
|
- "field_security" : { // optional
|
|
|
- "grant" : [ "title", "body" ]
|
|
|
- },
|
|
|
- "query": "{\"match\": {\"title\": \"foo\"}}" // optional
|
|
|
- }
|
|
|
- ],
|
|
|
- "run_as": [ "other_user" ], // optional
|
|
|
- "metadata" : { // optional
|
|
|
- "version" : 1
|
|
|
- }
|
|
|
-}
|
|
|
---------------------------------------------------
|
|
|
-// CONSOLE
|
|
|
-
|
|
|
-A successful call returns a JSON structure that shows whether the role has been
|
|
|
-created or updated.
|
|
|
-
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-{
|
|
|
- "role": {
|
|
|
- "created": true <1>
|
|
|
- }
|
|
|
-}
|
|
|
---------------------------------------------------
|
|
|
-// TESTRESPONSE
|
|
|
-<1> When an existing role is updated, `created` is set to false.
|
|
|
-
|
|
|
-[[security-api-get-role]]
|
|
|
-To retrieve a role from the `native` Security realm, issue a GET request to the
|
|
|
-`/_xpack/security/role/<rolename>` endpoint:
|
|
|
-
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-GET /_xpack/security/role/my_admin_role
|
|
|
---------------------------------------------------
|
|
|
-// CONSOLE
|
|
|
-// TEST[continued]
|
|
|
-
|
|
|
-A successful call returns an array of roles with the JSON representation of the
|
|
|
-role. If the role is not defined in the `native` realm, the request 404s.
|
|
|
-
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-{
|
|
|
- "my_admin_role": {
|
|
|
- "cluster" : [ "all" ],
|
|
|
- "indices" : [ {
|
|
|
- "names" : [ "index1", "index2" ],
|
|
|
- "privileges" : [ "all" ],
|
|
|
- "field_security" : {
|
|
|
- "grant" : [ "title", "body" ]
|
|
|
- },
|
|
|
- "query" : "{\"match\": {\"title\": \"foo\"}}"
|
|
|
- } ],
|
|
|
- "applications" : [ ],
|
|
|
- "run_as" : [ "other_user" ],
|
|
|
- "metadata" : {
|
|
|
- "version" : 1
|
|
|
- },
|
|
|
- "transient_metadata": {
|
|
|
- "enabled": true
|
|
|
- }
|
|
|
- }
|
|
|
-}
|
|
|
---------------------------------------------------
|
|
|
-// TESTRESPONSE
|
|
|
-
|
|
|
-You can specify multiple roles as a comma-separated list. To retrieve all roles,
|
|
|
-omit the role name.
|
|
|
-
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-# Retrieve roles "r1", "r2", and "my_admin_role"
|
|
|
-GET /_xpack/security/role/r1,r2,my_admin_role
|
|
|
-
|
|
|
-# Retrieve all roles
|
|
|
-GET /_xpack/security/role
|
|
|
---------------------------------------------------
|
|
|
-// CONSOLE
|
|
|
-// TEST[continued]
|
|
|
-
|
|
|
-NOTE: If single role is requested, that role is returned as the response. When
|
|
|
-requesting multiple roles, an object is returned holding the found roles, each
|
|
|
-keyed by the relevant role name.
|
|
|
-
|
|
|
-[[security-api-delete-role]]
|
|
|
-To delete a role, submit a DELETE request to the `/_xpack/security/role/<rolename>`
|
|
|
-endpoint:
|
|
|
-
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-DELETE /_xpack/security/role/my_admin_role
|
|
|
---------------------------------------------------
|
|
|
-// CONSOLE
|
|
|
-// TEST[continued]
|
|
|
-
|
|
|
-If the role is successfully deleted, the request returns `{"found": true}`.
|
|
|
-Otherwise, `found` is set to false.
|
|
|
-
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-{
|
|
|
- "found" : true
|
|
|
-}
|
|
|
---------------------------------------------------
|
|
|
-// TESTRESPONSE
|
|
|
-
|
|
|
-[[security-api-clear-role-cache]]
|
|
|
-The Clear Roles Cache API evicts roles from the native role cache. To clear the
|
|
|
-cache for a role, submit a POST request `/_xpack/security/role/<rolename>/_clear_cache`
|
|
|
-endpoint:
|
|
|
-
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-POST /_xpack/security/role/my_admin_role/_clear_cache
|
|
|
---------------------------------------------------
|
|
|
-// CONSOLE
|
|
|
+* <<security-api-put-role,Create role>>, <<security-api-delete-role,Delete role>>
|
|
|
+* <<security-api-clear-role-cache,Clear roles cache>>
|
|
|
+* <<security-api-get-role,Get roles>>
|