126 lines
3.9 KiB
Plaintext
126 lines
3.9 KiB
Plaintext
[role="xpack"]
|
|
[[security-api-put-role]]
|
|
=== Create or update roles API
|
|
++++
|
|
<titleabbrev>Create or update roles</titleabbrev>
|
|
++++
|
|
|
|
Adds and updates roles in the native realm.
|
|
|
|
[[security-api-put-role-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_security/role/<name>` +
|
|
|
|
`PUT /_security/role/<name>`
|
|
|
|
|
|
[[security-api-put-role-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* To use this API, you must have at least the `manage_security` cluster
|
|
privilege.
|
|
|
|
[[security-api-put-role-desc]]
|
|
==== {api-description-title}
|
|
|
|
The role management APIs are generally the preferred way to manage roles, rather than using
|
|
{stack-ov}/defining-roles.html#roles-management-file[file-based role management]. The create
|
|
or update roles API cannot update roles that are defined in roles files.
|
|
|
|
[[security-api-put-role-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`name`::
|
|
(string) The name of the role.
|
|
|
|
|
|
[[security-api-put-role-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
The following parameters can be specified in the body of a PUT or POST request
|
|
and pertain to adding a role:
|
|
|
|
`applications`:: (list) A list of application privilege entries.
|
|
`application` (required)::: (string) The name of the application to which this entry applies
|
|
`privileges`::: (list) A list of strings, where each element is the name of an application
|
|
privilege or action.
|
|
`resources`::: (list) A list resources to which the privileges are applied.
|
|
|
|
`cluster`:: (list) A list of cluster privileges. These privileges define the
|
|
cluster level actions that users with this role are able to execute.
|
|
|
|
`global`:: (object) An object defining global privileges. A global privilege is
|
|
a form of cluster privilege that is request-aware. Support for global privileges
|
|
is currently limited to the management of application privileges.
|
|
This field is optional.
|
|
|
|
`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].
|
|
|
|
[[security-api-put-role-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following example adds a role called `my_admin_role`:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_security/role/my_admin_role
|
|
{
|
|
"cluster": ["all"],
|
|
"indices": [
|
|
{
|
|
"names": [ "index1", "index2" ],
|
|
"privileges": ["all"],
|
|
"field_security" : { // optional
|
|
"grant" : [ "title", "body" ]
|
|
},
|
|
"query": "{\"match\": {\"title\": \"foo\"}}" // optional
|
|
}
|
|
],
|
|
"applications": [
|
|
{
|
|
"application": "myapp",
|
|
"privileges": [ "admin", "read" ],
|
|
"resources": [ "*" ]
|
|
}
|
|
],
|
|
"run_as": [ "other_user" ], // optional
|
|
"metadata" : { // optional
|
|
"version" : 1
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
A successful call returns a JSON structure that shows whether the role has been
|
|
created or updated.
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"role": {
|
|
"created": true <1>
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
<1> When an existing role is updated, `created` is set to false.
|