honeymoose/OpenSearch
1
0
Fork 0
mirror of https://github.com/honeymoose/OpenSearch.git synced 2025-03-25 17:38:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Formatted roles API (elastic/x-pack-elasticsearch#2577)

Browse Source 
* [DOCS] Formatted roles API

* [DOCS] Addressed feedback about roles API

Original commit: elastic/x-pack-elasticsearch@414d06bc13
This commit is contained in:
Lisa Cawley 2017-09-22 10:24:20 -07:00 committed by GitHub
parent 445af3ecf5
commit 3a6cba7bc9
1 changed files with 64 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
docs/en/rest-api/security/roles.asciidoc
View File

@ -3,10 +3,72 @@
=== Role Management APIs
The Roles API enables you to add, remove, and retrieve roles in the `native`
realm. To use this API, you must have at least the `manage_security` cluster
realm.
==== Request
`GET /_xpack/security/role` +
`GET /_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.
NOTE: The Roles API is now the preferred way to manage roles.
==== Examples
[[security-api-put-role]]
To add a role, submit a PUT or POST request to the `/_xpack/security/role/<rolename>`
@ -35,15 +97,6 @@ POST /_xpack/security/role/my_admin_role
--------------------------------------------------
// CONSOLE
The `name`, `cluster`, and `indices` fields are required at the top-level.
Within the `indices` array, the `names` and `privileges` fields are required.
Within the `metadata` object, keys beginning with `_` are reserved for system
usage.
The `field_security` and `query` fields are both optional. They are used to
implement field and document level security. For more information, see
{xpack-ref}/field-and-document-access-control.html[Setting Up Field and Document Level Security].
A successful call returns a JSON structure that shows whether the role has been
created or updated.