mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-29 18:03:32 -04:00
347 lines
12 KiB
Text
347 lines
12 KiB
Text
[role="xpack"]
|
|
[[security-api-bulk-put-role]]
|
|
=== Bulk create or update roles API
|
|
++++
|
|
<titleabbrev>Bulk create or update roles API</titleabbrev>
|
|
++++
|
|
|
|
.New API reference
|
|
[sidebar]
|
|
--
|
|
For the most up-to-date API details, refer to {api-es}/group/endpoint-security[Security APIs].
|
|
--
|
|
|
|
Bulk adds and updates roles in the native realm.
|
|
|
|
[[security-api-bulk-put-role-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_security/role/` +
|
|
|
|
[[security-api-bulk-put-role-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* To use this API, you must have at least the `manage_security` cluster
|
|
privilege.
|
|
|
|
[[security-api-bulk-put-role-desc]]
|
|
==== {api-description-title}
|
|
|
|
The role management APIs are generally the preferred way to manage roles, rather than using
|
|
<<roles-management-file,file-based role management>>. The bulk create
|
|
or update roles API cannot update roles that are defined in roles files.
|
|
|
|
[[security-api-bulk-put-role-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`refresh`::
|
|
Optional setting of the {ref}/docs-refresh.html[refresh policy] for the write request. Defaults to Immediate.
|
|
|
|
[[security-api-bulk-put-role-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
The following parameters can be specified in the body of a POST request
|
|
and pertain to adding a set of roles:
|
|
|
|
`roles`::
|
|
(object) The roles to add as a role name to role map.
|
|
|
|
====
|
|
`<role_name>` (required):: (string) The role name.
|
|
`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.
|
|
|
|
`indices`:: (list) A list of indices permissions entries.
|
|
`field_security`::: (object) The document fields that the owners of the role have
|
|
read access to. For more information, see
|
|
<<field-and-document-access-control>>.
|
|
`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
|
|
<<run-as-privilege>>.
|
|
|
|
`remote_indices`:: (list) A list of remote indices permissions entries.
|
|
+
|
|
--
|
|
NOTE: Remote indices are effective for <<remote-clusters-api-key,remote clusters configured with the API key based model>>.
|
|
They have no effect for remote clusters configured with the <<remote-clusters-cert,certificate based model>>.
|
|
--
|
|
`clusters` (required)::: (list) A list of cluster aliases to which the permissions
|
|
in this entry apply.
|
|
`field_security`::: (object) The document fields that the owners of the role have
|
|
read access to. For more information, see
|
|
<<field-and-document-access-control>>.
|
|
`names` (required)::: (list) A list of indices (or index name patterns) on the remote clusters
|
|
(specified with `clusters`) 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.
|
|
|
|
`remote_cluster`:: (list) A list of remote cluster permissions entries.
|
|
+
|
|
--
|
|
NOTE: Remote cluster permissions are effective for <<remote-clusters-api-key,remote clusters configured with the API key based model>>.
|
|
They have no effect for remote clusters configured with the <<remote-clusters-cert,certificate based model>>.
|
|
--
|
|
`clusters` (required)::: (list) A list of cluster aliases to which the permissions
|
|
in this entry apply.
|
|
`privileges`(required)::: (list) The cluster level privileges that the owners of the role
|
|
have in the specified clusters. Note - only a subset of the cluster privileges are supported for remote clusters.
|
|
The <<security-api-get-builtin-privileges-request, builtin privileges API>> can be used to determine
|
|
which privileges are allowed per version.
|
|
|
|
|
|
For more information, see <<defining-roles>>.
|
|
====
|
|
|
|
[[security-bulk-api-put-role-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following example adds the roles called `my_admin_role` and `my_user_role`:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_security/role
|
|
{
|
|
"roles": {
|
|
"my_admin_role": {
|
|
"cluster": [
|
|
"all"
|
|
],
|
|
"indices": [
|
|
{
|
|
"names": [
|
|
"index1",
|
|
"index2"
|
|
],
|
|
"privileges": [
|
|
"all"
|
|
],
|
|
"field_security": {
|
|
"grant": [
|
|
"title",
|
|
"body"
|
|
]
|
|
},
|
|
"query": "{\"match\": {\"title\": \"foo\"}}"
|
|
}
|
|
],
|
|
"applications": [
|
|
{
|
|
"application": "myapp",
|
|
"privileges": [
|
|
"admin",
|
|
"read"
|
|
],
|
|
"resources": [
|
|
"*"
|
|
]
|
|
}
|
|
],
|
|
"run_as": [
|
|
"other_user"
|
|
],
|
|
"metadata": {
|
|
"version": 1
|
|
}
|
|
},
|
|
"my_user_role": {
|
|
"cluster": [
|
|
"all"
|
|
],
|
|
"indices": [
|
|
{
|
|
"names": [
|
|
"index1"
|
|
],
|
|
"privileges": [
|
|
"read"
|
|
],
|
|
"field_security": {
|
|
"grant": [
|
|
"title",
|
|
"body"
|
|
]
|
|
},
|
|
"query": "{\"match\": {\"title\": \"foo\"}}"
|
|
}
|
|
],
|
|
"applications": [
|
|
{
|
|
"application": "myapp",
|
|
"privileges": [
|
|
"admin",
|
|
"read"
|
|
],
|
|
"resources": [
|
|
"*"
|
|
]
|
|
}
|
|
],
|
|
"run_as": [
|
|
"other_user"
|
|
],
|
|
"metadata": {
|
|
"version": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
A successful call returns a JSON structure that shows whether the role has been
|
|
created, updated, or had no changes made.
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"created": [ <1>
|
|
"my_admin_role", <2>
|
|
"my_user_role"
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
<1> Result type, one of `created`, `updated`, `noop`, `errors`.
|
|
<2> A list of the roles that were created.
|
|
|
|
Because errors are handled individually for each role create or update, the API allows partial success.
|
|
|
|
The following query would throw an error for `my_admin_role` because the privilege `bad_cluster_privilege`
|
|
doesn't exist, but would be successful for the `my_user_role`.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_security/role
|
|
{
|
|
"roles": {
|
|
"my_admin_role": {
|
|
"cluster": [
|
|
"bad_cluster_privilege"
|
|
],
|
|
"indices": [
|
|
{
|
|
"names": [
|
|
"index1",
|
|
"index2"
|
|
],
|
|
"privileges": ["all"],
|
|
"field_security": {
|
|
"grant": [
|
|
"title",
|
|
"body"
|
|
]
|
|
},
|
|
"query": "{\"match\": {\"title\": \"foo\"}}"
|
|
}
|
|
],
|
|
"applications": [
|
|
{
|
|
"application": "myapp",
|
|
"privileges": [
|
|
"admin",
|
|
"read"
|
|
],
|
|
"resources": [
|
|
"*"
|
|
]
|
|
}
|
|
],
|
|
"run_as": [
|
|
"other_user"
|
|
],
|
|
"metadata": {
|
|
"version": 1
|
|
}
|
|
},
|
|
"my_user_role": {
|
|
"cluster": [
|
|
"all"
|
|
],
|
|
"indices": [
|
|
{
|
|
"names": [
|
|
"index1"
|
|
],
|
|
"privileges": [
|
|
"read"
|
|
],
|
|
"field_security": {
|
|
"grant": [
|
|
"title",
|
|
"body"
|
|
]
|
|
},
|
|
"query": "{\"match\": {\"title\": \"foo\"}}"
|
|
}
|
|
],
|
|
"applications": [
|
|
{
|
|
"application": "myapp",
|
|
"privileges": [
|
|
"admin",
|
|
"read"
|
|
],
|
|
"resources": [
|
|
"*"
|
|
]
|
|
}
|
|
],
|
|
"run_as": [
|
|
"other_user"
|
|
],
|
|
"metadata": {
|
|
"version": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
The result would then have the `errors` field set to `true` and hold the error for the `my_admin_role` update.
|
|
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"created": [
|
|
"my_user_role" <1>
|
|
],
|
|
"errors": { <2>
|
|
"count": 1, <3>
|
|
"details": {
|
|
"my_admin_role": { <4>
|
|
"type": "action_request_validation_exception",
|
|
"reason": "Validation Failed: 1: unknown cluster privilege [bad_cluster_privilege]. a privilege must be either one of the predefined cluster privilege names [manage_own_api_key,manage_data_stream_global_retention,monitor_data_stream_global_retention,none,cancel_task,cross_cluster_replication,cross_cluster_search,delegate_pki,grant_api_key,manage_autoscaling,manage_index_templates,manage_logstash_pipelines,manage_oidc,manage_saml,manage_search_application,manage_search_query_rules,manage_search_synonyms,manage_service_account,manage_token,manage_user_profile,monitor_connector,monitor_enrich,monitor_inference,monitor_ml,monitor_rollup,monitor_snapshot,monitor_stats,monitor_text_structure,monitor_watcher,post_behavioral_analytics_event,read_ccr,read_connector_secrets,read_fleet_secrets,read_ilm,read_pipeline,read_security,read_slm,transport_client,write_connector_secrets,write_fleet_secrets,create_snapshot,manage_behavioral_analytics,manage_ccr,manage_connector,manage_enrich,manage_ilm,manage_inference,manage_ml,manage_rollup,manage_slm,manage_watcher,monitor_data_frame_transforms,monitor_transform,manage_api_key,manage_ingest_pipelines,manage_pipeline,manage_data_frame_transforms,manage_transform,manage_security,monitor,manage,all] or a pattern over one of the available cluster actions;"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
<1> The successfully created role.
|
|
<2> The errors encountered.
|
|
<3> The number of put role requests that resulted in an error.
|
|
<4> The error keyed by role name.
|