103 lines
2.9 KiB
Plaintext
103 lines
2.9 KiB
Plaintext
|
[role="xpack"]
|
||
|
|
[[security-api-put-role]]
|
||
|
|
=== Create roles API
|
||
|
|
|
||
|
|
Adds roles in the native realm.
|
||
|
|
|
||
|
|
==== Request
|
||
|
|
|
||
|
|
`POST /_xpack/security/role/<name>` +
|
||
|
|
|
||
|
|
`PUT /_xpack/security/role/<name>`
|
||
|
|
|
||
|
|
|
||
|
|
==== Description
|
||
|
|
|
||
|
|
The role API is generally the preferred way to manage roles, rather than using
|
||
|
|
file-based role management. For more information about the native realm, see
|
||
|
|
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
|
||
|
|
|
||
|
|
|
||
|
|
==== Path Parameters
|
||
|
|
|
||
|
|
`name`::
|
||
|
|
(string) The name of the role.
|
||
|
|
|
||
|
|
|
||
|
|
==== 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
|
||
|
|
{stack-ov}/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
|
||
|
|
{stack-ov}/run-as-privilege.html[Submitting requests on behalf of other users].
|
||
|
|
|
||
|
|
For more information, see {stack-ov}/defining-roles.html[Defining roles].
|
||
|
|
|
||
|
|
|
||
|
|
==== Authorization
|
||
|
|
|
||
|
|
To use this API, you must have at least the `manage_security` cluster
|
||
|
|
privilege.
|
||
|
|
|
||
|
|
|
||
|
|
==== Examples
|
||
|
|
|
||
|
|
The following example adds a role called `my_admin_role`:
|
||
|
|
|
||
|
|
[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.
|