mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-09 14:34:43 +00:00
f785c31531
This commit clarifies and points out that the Role management UI and the Role management API cannot be used to manage roles that are defined in roles.yml and that file based role management is intended to have a small administrative scope and not handle all possible RBAC use cases.
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.
|