deploy and manage > users and roles > cluster/deployment > roles

deploy-manage/_snippets/field-doc-sec-limitations.md

@@ -0,0 +1,44 @@
+Field and document security is subject to the following limitations: 
+
+### Document level security limitations
+
+When a user’s role enables [document level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for a data stream or index:
+
+* Document level security doesn’t affect global index statistics that relevancy scoring uses. This means that scores are computed without taking the role query into account. Documents that don’t match the role query are never returned.
+* The `has_child` and `has_parent` queries aren’t supported as query parameters in the role definition. The `has_child` and `has_parent` queries can be used in the search API with document level security enabled.
+* [Date math](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/rest-apis/common-options.md#date-math) expressions cannot contain `now` in [range queries with date fields](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/query-dsl-range-query.md#ranges-on-dates).
+* Any query that makes remote calls to fetch query data isn’t supported, including the following queries:
+
+    * `terms` query with terms lookup
+    * `geo_shape` query with indexed shapes
+    * `percolate` query
+
+* If suggesters are specified and document level security is enabled, the specified suggesters are ignored.
+* A search request cannot be profiled if document level security is enabled.
+* The [terms enum API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-terms-enum) does not return terms if document level security is enabled.
+* The [`multi_match`](asciidocalypse://docs/elasticsearch/docs/reference/query-languages/query-dsl-multi-match-query.md) query does not support specifying fields using wildcards.
+
+:::{note} 
+While document-level security prevents users from viewing restricted documents, it’s still possible to write search requests that return aggregate information about the entire index. A user whose access is restricted to specific documents in an index could still learn about field names and terms that only exist in inaccessible documents, and count how many inaccessible documents contain a given term.
+:::
+
+### Field level security limitations
+
+When a user’s role enables document or [field level security](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md) for a data stream or index:
+
+* The user cannot perform write operations:
+
+    * The update API isn’t supported.
+    * Update requests included in bulk requests aren’t supported.
+
+* The user cannot perform operations that effectively make contents accessible under another name, including actions from the following APIs:
+
+    * [Clone index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-clone)
+    * [Shrink index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-shrink)
+    * [Split index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-split)
+    * [Aliases API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-update-aliases)
+
+* The request cache is disabled for search requests if either of the following are true:
+
+    * The role query that defines document level security is [templated](/deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#templating-role-query) using a [stored script](/explore-analyze/scripting/modules-scripting-using.md#script-stored-scripts).
+    * The target indices are a mix of local and remote indices.

deploy-manage/api-keys/serverless-project-api-keys.md

@@ -70,7 +70,7 @@ For example, the following `role_descriptors` object defines a `books-read-only`
 }
 ```
 
-For the `role_descriptors` object schema, check out the [`/_security/api_key` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-security-create-api-key) docs. For supported privileges, check [Security privileges](../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices).
+For the `role_descriptors` object schema, check out the [`/_security/api_key` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-security-create-api-key) docs. For supported privileges, check [Security privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices).
 
 
 ## Update an API key [api-keys-update-an-api-key]

deploy-manage/remote-clusters/ec-remote-cluster-ece.md

@@ -299,4 +299,4 @@ The response will include just the remote clusters from the same {{ecloud}} orga
 
 ## Configure roles and users [ec_configure_roles_and_users_3]
 
-To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).
+To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).

deploy-manage/remote-clusters/ec-remote-cluster-other-ess.md

@@ -237,4 +237,4 @@ The response will include just the remote clusters from the same {{ecloud}} orga
 
 ## Configure roles and users [ec_configure_roles_and_users_2]
 
-To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).
+To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).

deploy-manage/remote-clusters/ec-remote-cluster-same-ess.md

@@ -274,4 +274,4 @@ The response will include just the remote clusters from the same {{ecloud}} orga
 
 ## Configure roles and users [ec_configure_roles_and_users]
 
-To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).
+To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).

deploy-manage/remote-clusters/ec-remote-cluster-self-managed.md

@@ -324,4 +324,4 @@ The response will include just the remote clusters from the same {{ecloud}} orga
 
 ## Configure roles and users [ec_configure_roles_and_users_4]
 
-To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).
+To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).

deploy-manage/remote-clusters/ece-remote-cluster-ece-ess.md

@@ -248,4 +248,4 @@ The response includes just the remote clusters from the same ECE environment. In
 
 ## Configure roles and users [ece_configure_roles_and_users_3]
 
-To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).
+To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).

deploy-manage/remote-clusters/ece-remote-cluster-other-ece.md

@@ -321,4 +321,4 @@ The response includes just the remote clusters from the same ECE environment. In
 
 ## Configure roles and users [ece_configure_roles_and_users_2]
 
-To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).
+To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).

deploy-manage/remote-clusters/ece-remote-cluster-same-ece.md

@@ -277,4 +277,4 @@ The response includes just the remote clusters from the same ECE environment. In
 
 ## Configure roles and users [ece_configure_roles_and_users]
 
-To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).
+To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).

deploy-manage/remote-clusters/ece-remote-cluster-self-managed.md

@@ -328,4 +328,4 @@ The response includes just the remote clusters from the same ECE environment. In
 
 ## Configure roles and users [ece_configure_roles_and_users_4]
 
-To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).
+To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) on the local cluster. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key).

deploy-manage/remote-clusters/remote-clusters-api-key.md

@@ -321,7 +321,7 @@ cluster:
 
 ## Configure roles and users [remote-clusters-privileges-api-key]
 
-To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) or [remote cluster privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-cluster-priv) on the local cluster.
+To use a remote cluster for {{ccr}} or {{ccs}}, you need to create user roles with [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) or [remote cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-cluster-priv) on the local cluster.
 
 You can manage users and roles from Stack Management in {{kib}} by selecting **Security > Roles** from the side navigation. You can also use the [role management APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-security) to add, update, remove, and retrieve roles dynamically.
 

deploy-manage/remote-clusters/remote-clusters-migrate.md

@@ -117,7 +117,7 @@ On the local cluster, stop any persistent tasks that refer to the remote cluster
 
 On the local cluster:
 
-1. Enhance any roles used by local cluster users with the required [remote indices privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-indices-priv) or [remote cluster privileges](../users-roles/cluster-or-deployment-auth/defining-roles.md#roles-remote-cluster-priv) for {{ccr}} and {{ccs}}. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). Note:
+1. Enhance any roles used by local cluster users with the required [remote indices privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-indices-priv) or [remote cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/role-structure.md#roles-remote-cluster-priv) for {{ccr}} and {{ccs}}. Refer to [Configure roles and users](remote-clusters-api-key.md#remote-clusters-privileges-api-key). Note:
 
     * You only need to assign additional `remote_indices` or `remote_cluster` privileges to existing roles used for cross-cluster operations. You should be able to copy these privileges from the original roles on the remote cluster, where they are defined under the certification based security model.
     * The roles on the local cluster can’t exceed the `access` privilege granted by the cross-cluster API key. Any extra local privileges will be suppressed by the cross-cluster API key’s privileges.

deploy-manage/security/secure-endpoints.md

@@ -27,5 +27,5 @@ While you absolutely shouldn’t expose {{es}} directly to the internet, you als
 
 ## Implement role based access control [security-create-appropriate-users] 
 
-[Define roles](../users-roles/cluster-or-deployment-auth/defining-roles.md) for your users and [assign appropriate privileges](../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to ensure that users have access only to the resources that they need. This process determines whether the user behind an incoming request is allowed to run that request.
+[Define roles](../users-roles/cluster-or-deployment-auth/defining-roles.md) for your users and [assign appropriate privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md) to ensure that users have access only to the resources that they need. This process determines whether the user behind an incoming request is allowed to run that request.
 

deploy-manage/toc.yml

@@ -594,7 +594,7 @@ toc:
               - file: users-roles/cloud-enterprise-orchestrator/ldap.md
               - file: users-roles/cloud-enterprise-orchestrator/saml.md
           - file: users-roles/cloud-enterprise-orchestrator/configure-sso-for-deployments.md
-      - file: users-roles/custom-roles.md
+      - file: users-roles/serverless-custom-roles.md
       - file: users-roles/cluster-or-deployment-auth.md
         children:
           - file: users-roles/cluster-or-deployment-auth/quickstart.md
@@ -646,14 +646,18 @@ toc:
               - file: users-roles/cluster-or-deployment-auth/manage-authentication-for-multiple-clusters.md
           - file: users-roles/cluster-or-deployment-auth/user-roles.md
             children:
+              - file: users-roles/cluster-or-deployment-auth/built-in-roles.md
               - file: users-roles/cluster-or-deployment-auth/defining-roles.md
                 children:
+                  - file: users-roles/cluster-or-deployment-auth/role-structure.md
                   - file: users-roles/cluster-or-deployment-auth/granting-privileges-for-data-streams-aliases.md
+                  - file: users-roles/cluster-or-deployment-auth/kibana-role-management.md
                   - file: users-roles/cluster-or-deployment-auth/role-restriction.md
-              - file: users-roles/cluster-or-deployment-auth/built-in-roles.md
-              - file: users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md
+              - file: users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md                  
               - file: users-roles/cluster-or-deployment-auth/kibana-privileges.md
               - file: users-roles/cluster-or-deployment-auth/mapping-users-groups-to-roles.md
+                children:
+                  - file: users-roles/cluster-or-deployment-auth/role-mapping-resources.md
               - file: users-roles/cluster-or-deployment-auth/authorization-delegation.md
               - file: users-roles/cluster-or-deployment-auth/authorization-plugins.md
               - file: users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md

deploy-manage/tools/snapshot-and-restore/create-snapshots.md

@@ -26,8 +26,8 @@ The guide also provides tips for creating dedicated cluster state snapshots and
 
 * To use {{kib}}'s **Snapshot and Restore** feature, you must have the following permissions:
 
-    * [Cluster privileges](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository`
-    * [Index privilege](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the `monitor` index
+    * [Cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository`
+    * [Index privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the `monitor` index
 
 * You can only take a snapshot from a running cluster with an elected [master node](../../distributed-architecture/clusters-nodes-shards/node-roles.md#master-node-role).
 * A snapshot repository must be [registered](self-managed.md) and available to the cluster.
@@ -59,7 +59,7 @@ Elastic Cloud Hosted deployments automatically include the `cloud-snapshot-polic
 
 ### {{slm-init}} security [slm-security]
 
-The following [cluster privileges](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) control access to the {{slm-init}} actions when {{es}} {{security-features}} are enabled:
+The following [cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster) control access to the {{slm-init}} actions when {{es}} {{security-features}} are enabled:
 
 `manage_slm`
 :   Allows a user to perform all {{slm-init}} actions, including creating and updating policies and starting and stopping {{slm-init}}.

deploy-manage/tools/snapshot-and-restore/self-managed.md

@@ -20,8 +20,8 @@ In this guide, you’ll learn how to:
 
 * To use {{kib}}'s **Snapshot and Restore** feature, you must have the following permissions:
 
-    * [Cluster privileges](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository`
-    * [Index privilege](../../users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the `monitor` index
+    * [Cluster privileges](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-cluster): `monitor`, `manage_slm`, `cluster:admin/snapshot`, and `cluster:admin/repository`
+    * [Index privilege](/deploy-manage/users-roles/cluster-or-deployment-auth/elasticsearch-privileges.md#privileges-list-indices): `all` on the `monitor` index
 
 * To register a snapshot repository, the cluster’s global metadata must be writeable. Ensure there aren’t any [cluster blocks](asciidocalypse://docs/elasticsearch/docs/reference/elasticsearch/configuration-reference/miscellaneous-cluster-settings.md#cluster-read-only) that prevent write access.