[role="xpack"]
[[security-privileges]]
=== Security privileges

This section lists the privileges that you can assign to a role.

[[privileges-list-cluster]]
==== Cluster privileges

[horizontal]
`all`::
All cluster administration operations, like snapshotting, node shutdown/restart,
settings update, rerouting, or managing users and roles.

`create_snapshot`::
Privileges to create snapshots for existing repositories. Can also list and view
details on existing repositories and snapshots.

`grant_api_key`::
Privileges to create {es} API keys on behalf of other users.

`monitor_snapshot`::
Privileges to list and view details on existing repositories and snapshots.

`manage`::
Builds on `monitor` and adds cluster operations that change values in the cluster.
This includes snapshotting, updating settings, and rerouting. It also includes
obtaining snapshot and restore status. This privilege does not include the
ability to manage security.

`manage_api_key`::
All security-related operations on {es} API keys including
<<security-api-create-api-key,creating new API keys>>,
<<security-api-get-api-key,retrieving information about API keys>>, and
<<security-api-invalidate-api-key,invalidating API keys>>.
+
--
[NOTE]
======

* When you create new API keys, they will always be owned by the authenticated
user.
* When you have this privilege, you can invalidate your own API keys and those
owned by other users.

======

--

`manage_ccr`::
All {ccr} operations related to managing follower indices and auto-follow
patterns. It also includes the authority to grant the privileges necessary to
manage follower indices and auto-follow patterns. This privilege is necessary
only on clusters that contain follower indices.

`manage_ilm`::
All {Ilm} operations related to managing policies.

`manage_index_templates`::
All operations on index templates.

`manage_ingest_pipelines`::
All operations on ingest node pipelines.

`manage_logstash_pipelines`::
All operations on logstash pipelines.

`manage_ml`::
All {ml} operations, such as creating and deleting {dfeeds}, jobs, and model
snapshots.
+
--
NOTE: {dfeeds-cap} that were created prior to version 6.2 or created when
{security-features} were disabled run as a system user with elevated privileges,
including permission to read all indices. Newer {dfeeds} run with the security
roles of the user who created or updated them.

--

`manage_own_api_key`::
All security-related operations on {es} API keys that are owned by the current
authenticated user. The operations include
<<security-api-create-api-key,creating new API keys>>,
<<security-api-get-api-key,retrieving information about API keys>>, and
<<security-api-invalidate-api-key,invalidating API keys>>.

`manage_pipeline`::
All operations on ingest pipelines.

`manage_rollup`::
All rollup operations, including creating, starting, stopping and deleting
rollup jobs.

`manage_saml`::
Enables the use of internal {es} APIs to initiate and manage SAML authentication
on behalf of other users.

`manage_security`::
All security-related operations such as CRUD operations on users and roles and
cache clearing.

`manage_slm`::
All {slm} ({slm-init}) actions, including creating and updating policies and
starting and stopping {slm-init}.

`manage_token`::
All security-related operations on tokens that are generated by the {es} Token
Service.

`manage_transform`::
All operations related to managing {transforms}.

`manage_watcher`::
All watcher operations, such as putting watches, executing, activate or acknowledging.
+
--
NOTE: Watches that were created prior to version 6.1 or created when the
{security-features} were disabled run as a system user with elevated privileges,
including permission to read and write all indices. Newer watches run with the
security roles of the user who created or updated them.

--

`monitor`::
All cluster read-only operations, like cluster health and state, hot threads,
node info, node and cluster stats, and pending cluster tasks.

`monitor_transform`::
All read-only operations related to {transforms}.

`monitor_ml`::
All read-only {ml} operations, such as getting information about {dfeeds}, jobs,
model snapshots, or results.

`monitor_rollup`::
All read-only rollup operations, such as viewing the list of historical and
currently running rollup jobs and their capabilities.

`monitor_watcher`::
All read-only watcher operations, such as getting a watch and watcher stats.

`read_ccr`::
All read-only {ccr} operations, such as getting information about indices and
metadata for leader indices in the cluster. It also includes the authority to
check whether users have the appropriate privileges to follow leader indices.
This privilege is necessary only on clusters that contain leader indices.

`read_ilm`::
All read-only {Ilm} operations, such as getting policies and checking the
status of {Ilm}

read_slm::
All read-only {slm-init} actions, such as getting policies and checking the
{slm-init} status.

`transport_client`::
All privileges necessary for a transport client to connect.  Required by the remote
cluster to enable <<cross-cluster-configuring,Cross Cluster Search>>.

[[privileges-list-indices]]
==== Indices privileges

[horizontal]
`all`::
Any action on an index or data stream.

`auto_configure`::
Permits auto-creation of indices and data streams. An auto-create action is the
result of an <<docs-index_,index>> or <<docs-bulk,bulk>> request that targets a
non-existent index or data stream rather than an explicit
<<indices-create-index,create index>> or
<<indices-create-data-stream,create data stream>> request. Also permits
auto-update of mappings on indices and data streams if they do not contradict
existing mappings. An auto-update mapping action is the result of an index or
bulk request on an index or data stream that contains new fields that may
be mapped rather than an explicit <<indices-put-mapping,put mapping>> request.

`create`::
Privilege to index documents, allowing overwriting any existing document, but
not permitting updating one.
+
deprecated:[7.9] Also grants the permission to update the index mapping (but not
the data stream mapping), using the update mapping action, or relying on
{ref}/dynamic-mapping.html[dynamic mappings]. In the next major release,
this privilege will not grant any mapping update permission.
+
--
NOTE: This privilege does not restrict the index operation to the creation
of documents but instead restricts API use to the index API. The index API
allows a user to overwrite a previously indexed document. See the `create_doc`
privilege for an alternative.

--

`create_doc`::
Privilege to index new documents, without allowing overwriting or updating
existing ones.
+
deprecated:[7.9] Also grants the permission to update the index mapping (but not
the data stream mapping), using the update mapping action, or relying on
{ref}/dynamic-mapping.html[dynamic mappings]. In the next major release,
this privilege will not grant any mapping update permission.
+
--
[NOTE]
====

This privilege relies on the `op_type` of indexing requests (<<docs-index_>> and
<<docs-bulk>>). When ingesting documents as a user who has the `create_doc`
privilege (and no higher privilege such as `index` or `write`), you must ensure that
'op_type' is set to 'create' through one of the following:

* Explicitly setting the `op_type` in the index or bulk APIs
* Using the `_create` endpoint for the index API
* Creating a document with an auto-generated `_id`
====

--

`create_index`::
Privilege to create an index or data stream. A create index request may contain
aliases to be added to the index once created. In that case the request
requires the `manage` privilege as well, on both the index and the aliases
names.

`delete`::
Privilege to delete documents.

`delete_index`::
Privilege to delete an index or data stream.

`index`::
Privilege to index (overwriting included) and update documents.
+
deprecated:[7.9] Also grants the permission to update the index mapping (but not
the data stream mapping), using the update mapping action, or relying on
{ref}/dynamic-mapping.html[dynamic mappings]. In the next major release,
this privilege will not grant any mapping update permission.

`maintenance`::
Permits refresh, flush, synced flush and force merge index administration operations.
No privilege to read or write index data or otherwise manage the index.

`manage`::
All `monitor` privileges plus index and data stream administration (aliases,
analyze, cache clear, close, delete, exists, flush, mapping, open, force merge,
refresh, settings, search shards, templates, validate).

`manage_follow_index`::
All actions that are required to manage the lifecycle of a follower index, which
includes creating a follower index, closing it, and converting it to a regular
index. This privilege is necessary only on clusters that contain follower indices.

`manage_ilm`::
All {Ilm} operations relating to managing the execution of policies of an index
or data stream. This includes operations such as retrying policies and removing
a policy from an index or data stream.

`manage_leader_index`::
All actions that are required to manage the lifecycle of a leader index, which
includes {ref}/ccr-post-forget-follower.html[forgetting a follower]. This
privilege is necessary only on clusters that contain leader indices.

`monitor`::
All actions that are required for monitoring (recovery, segments info, index
stats and status).

`read`::
Read-only access to actions (count, explain, get, mget, get indexed scripts,
more like this, multi percolate/search/termvector, percolate, scroll,
clear_scroll, search, suggest, tv).

`read_cross_cluster`::
Read-only access to the search action from a <<cross-cluster-configuring,remote cluster>>.

`view_index_metadata`::
Read-only access to index and data stream metadata (aliases, aliases exists,
get index, get data stream, exists, field mappings, mappings, search shards,
type exists, validate, warmers, settings, ilm). This privilege is available
for use primarily by {kib} users.

`write`::
Privilege to perform all write operations to documents, which includes the
permission to index, update, and delete documents as well as performing bulk
operations, and allows the {ref}/dynamic-mapping.html[dynamic mapping updates]
as a result of these.
+
deprecated:[7.9] Until the next major release, this also grants access to the
update mapping action, but only on indices, not on data streams.

==== Run as privilege

The `run_as` permission enables an authenticated user to submit requests on
behalf of another user. The value can be a user name or a comma-separated list
of user names. (You can also specify users as an array of strings or a YAML
sequence.) For more information, see
<<run-as-privilege, Submitting Requests on Behalf of Other Users>>.

[[application-privileges]]
==== Application privileges

Application privileges are managed within {es} and can be retrieved with the
<<security-api-has-privileges,has privileges API>> and the
<<security-api-get-privileges,get application privileges API>>. They do
not, however, grant access to any actions or resources within {es}. Their
purpose is to enable applications to represent and store their own privilege
models within {es} roles.

To create application privileges, use the
<<security-api-put-privileges,add application privileges API>>. You can
then associate these application privileges with roles, as described in
<<defining-roles>>.
