mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-29 18:03:32 -04:00
9185056efe
In this PR we remove unused code including relating to the global data retention with APIs implementation: - The transport action for updating, deleting and retrieving the global retention. - The `DataStreamGlobalRetention` from the cluster state (this should be bwc safe because we never exposed the APIs to add a data stream lifecycle to the cluster state). - Make unused privileges monitor and managing global retention a noop. - Remove cluster state update tasks. The kept `DataStreamGlobalRetentionResolver` considering it could hold and provide the global retention from the settings when we implement it. We just renamed it to DataStreamGlobalRetentionProvider for now to better match what it does. The factory retention settings should still work after this change.
328 lines
11 KiB
Text
328 lines
11 KiB
Text
[role="xpack"]
|
|
[[security-api-bulk-put-role]]
|
|
=== Bulk create or update roles API
|
|
preview::[]
|
|
++++
|
|
<titleabbrev>Bulk create or update roles API</titleabbrev>
|
|
++++
|
|
|
|
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`:: beta:[] (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.
|
|
|
|
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_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.
|