[DOCS] Updating doc level security limitations (#64426) (#64660)

* Updating doc level security limitations.

* Incorporating review feedback.

* Changes from review feedback.

* Remove statement about the stats API.

x-pack/docs/en/security/authorization/document-level-security.asciidoc

@@ -3,19 +3,31 @@
 === Document level security
 
 Document level security restricts the documents that users have read access to.
-In particular, it restricts which documents can be accessed from document-based 
+In particular, it restricts which documents can be accessed from document-based
-read APIs. 
+read APIs.
 
 To enable document level security, you use a query to specify the documents that
-each role can access. The document query is associated with a particular data
+each role can access. The document `query` is associated with a particular data
 stream, index, or wildcard (`*`) pattern and operates in conjunction with the
 privileges specified for the data streams and indices.
 
+The specified document `query`:
+
+* Expects the same format as if it was defined in the search request
+* Supports <<templating-role-query,templating a role query>> that can access
+the details of the currently authenticated user
+* Accepts queries written as either string values or nested JSON
+* Supports the majority of the {es}
+<<query-dsl,Query Domain Specific Language (DSL)>>, with <<field-document-limitations,some limitations>> for field and document level security
+
+IMPORTANT: Omitting the `query` parameter entirely disables document level
+security for the respective indices permission entry.
+
 The following role definition grants read access only to documents that
 belong to the `click` category within all the `events-*` data streams and indices:
 
 [source,console]
---------------------------------------------------
+----
 POST /_security/role/click_role
 {
   "indices": [
@@ -26,19 +38,33 @@ POST /_security/role/click_role
     }
   ]
 }
---------------------------------------------------
+----
 
-NOTE: Omitting the `query` entry entirely disables document level security for
+You can write this same query using nested JSON syntax:
-      the respective indices permission entry.
 
-The specified `query` expects the same format as if it was defined in the
+[source,console]
-search request and supports the full {es} {ref}/query-dsl.html[Query DSL].
+----
+POST _security/role/click_role
+{
+  "indices": [
+    {
+      "names": [ "events-*" ],
+      "privileges": [ "read" ],
+      "query": {
+        "match": {
+          "category": "click"
+        }
+      }
+    }
+  ]
+}
+----
 
-For example, the following role grants read access only to the documents whose
+The following role grants read access only to the documents whose
 `department_id` equals `12`:
 
 [source,console]
---------------------------------------------------
+----
 POST /_security/role/dept_role
 {
   "indices" : [
@@ -51,8 +77,4 @@ POST /_security/role/dept_role
     }
   ]
 }
---------------------------------------------------
+----
-
-NOTE: `query` also accepts queries written as string values.
-
-For more information, see <<field-and-document-access-control>>.

x-pack/docs/en/security/limitations.asciidoc

@@ -9,8 +9,8 @@
 [discrete]
 === Plugins
 
-Elasticsearch's plugin infrastructure is extremely flexible in terms of what can
+{es}'s plugin infrastructure is extremely flexible in terms of what can
-be extended. While it opens up Elasticsearch to a wide variety of (often custom)
+be extended. While it opens up {es} to a wide variety of (often custom)
 additional functionality, when it comes to security, this high extensibility level
 comes at a cost. We have no control over the third-party plugins' code (open
 source or not) and therefore we cannot guarantee their compliance with
@@ -20,7 +20,7 @@ officially supported on clusters with {security-features} enabled.
 [discrete]
 === Changes in wildcard behavior
 
-Elasticsearch clusters with the {security-features} enabled apply the `/_all`
+{es} clusters with the {security-features} enabled apply the `/_all`
 wildcard, and all other wildcards, to the data streams, indices, and index aliases that the current user has
 privileges for, not all data streams, indices, and index aliases on the cluster.
 
@@ -38,44 +38,43 @@ Aliases containing filters are not a secure way to restrict access to individual
 documents, due to the limitations described in
 <<alias-limitations, Index and field names can be leaked when using aliases>>.
 The {stack-security-features} provide a secure way to restrict access to
-documents through the 
+documents through the
 <<field-and-document-access-control, document-level security>> feature.
 
 [discrete]
+[[field-document-limitations]]
 === Field and document level security limitations
 
-When a user's role enables document or field level security for a data stream or index:
+When a user's role enables document or <<field-level-security,field level security>> 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 request cache is disabled for search requests.
 
-When a user's role enables document level security for a data stream or index:
+When a user's role enables <<document-level-security,document level security>> for a data stream or index:
 
-* Document level security isn't applied for APIs that aren't document based.
-  An example is the field stats API.
 * Document level security doesn't affect global index statistics that relevancy
-  scoring uses. So this means that scores are computed without taking the role
+  scoring uses. This means that scores are computed without taking the role
-  query into account. Note that documents not matching with the role query are
+  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 in the
+* The `has_child` and `has_parent` queries aren't supported as query parameters
-  role definition. The `has_child` and `has_parent` queries can be used in the
+in the role definition. The `has_child` and `has_parent` queries can be used in
-  search API with document level security enabled.
+the search API with document level security enabled.
-* Any query that makes remote calls to fetch data to query by isn't supported.
+* <<date-math,Date math>> expressions cannot contain `now` in <<ranges-on-dates,range queries with date fields>>
-  The following queries aren't supported:
+* Any query that makes remote calls to fetch query data isn't supported,
-** The `terms` query with terms lookup isn't supported.
+including the following queries:
-** The `geo_shape` query with indexed shapes isn't supported.
+** `terms` query with terms lookup
-** The `percolate` query isn't supported.
+** `geo_shape` query with indexed shapes
-* If suggesters are specified and document level security is enabled then
+** `percolate` query
-  the specified suggesters are ignored.
+* 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.
 
 [discrete]
 [[alias-limitations]]
 === Index and field names can be leaked when using aliases
 
-Calling certain Elasticsearch APIs on an alias can potentially leak information
+Calling certain {es} APIs on an alias can potentially leak information
 about indices that the user isn't authorized to access. For example, when you get
 the mappings for an alias with the `_mapping` API, the response includes the
 index name and mappings for each index that the alias applies to.