Add 'DLS and multiple roles' section to DLS topic (#6408)

* explaination of setting plugins.security.dfm_empty_overrides_all: true Signed-off-by: [email protected] <[email protected]> * datadog grammer corrected in documentation Signed-off-by: [email protected] <[email protected]> * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <[email protected]> Signed-off-by: leanneeliatra <[email protected]> * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <[email protected]> Signed-off-by: leanneeliatra <[email protected]> * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <[email protected]> Signed-off-by: leanneeliatra <[email protected]> * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <[email protected]> Signed-off-by: leanneeliatra <[email protected]> * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <[email protected]> Signed-off-by: leanneeliatra <[email protected]> * adding more examples of setting for dsl to make it clearer Signed-off-by: [email protected] <[email protected]> * small edits to fix spacing in previous commit Signed-off-by: [email protected] <[email protected]> * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <[email protected]> Signed-off-by: leanneeliatra <[email protected]> * reviewdog fixes Signed-off-by: [email protected] <[email protected]> * Formatting edits. Signed-off-by: Naarcha-AWS <[email protected]> * Update document-level-security.md Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> --------- Signed-off-by: [email protected] <[email protected]> Signed-off-by: leanneeliatra <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> Co-authored-by: [email protected] <[email protected]> Co-authored-by: leanneeliatra <[email protected]> Co-authored-by: Naarcha-AWS <[email protected]> Co-authored-by: Nathan Bower <[email protected]>
opensearch-project · Mar 1, 2024 · 93d07a0 · 93d07a0
1 parent b3be567
commit 93d07a0
Showing 1 changed file with 94 additions and 0 deletions.
diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md
@@ -185,3 +185,97 @@ plugins.security.dls.mode: filter-level
 Lucene-level DLS | `lucene-level` | This setting makes all DLS queries apply to the Lucene level. | Lucene-level DLS modifies Lucene queries and data structures directly. This is the most efficient mode but does not allow certain advanced constructs in DLS queries, including TLQs.
 Filter-level DLS | `filter-level` | This setting makes all DLS queries apply to the filter level. | In this mode, OpenSearch applies DLS by modifying queries that OpenSearch receives. This allows for term-level lookup queries in DLS queries, but you can only use the `get`, `search`, `mget`, and `msearch` operations to retrieve data from the protected index. Additionally, cross-cluster searches are limited with this mode.
 Adaptive | `adaptive-level` | The default setting that allows OpenSearch to automatically choose the mode. | DLS queries without TLQs are executed in Lucene-level mode, while DLS queries that contain TLQ are executed in filter- level mode.
+
+## DLS and multiple roles
+
+OpenSearch combines all DLS queries with the logical `OR` operator. However, when a role that uses DLS is combined with another security role that doesn't use DLS, the query results are filtered to display only documents matching the DLS from the first role. This filter rule also applies to roles that do not grant read documents.
+
+### When to enable `plugins.security.dfm_empty_overrides_all`
+
+When to enable the `plugins.security.dfm_empty_overrides_all` setting depends on whether you want to restrict user access to documents without DLS. 
+
+
+To ensure access is not restricted, you can set the following configuration in `opensearch.yml`:
+
+```
+plugins.security.dfm_empty_overrides_all: true
+```
+{% include copy.html %}
+
+
+The following examples show what level of access roles with DLS enabled and without DLS enabled, depending on the interaction. These examples can help you decide when to enable the `plugins.security.dfm_empty_overrides_all` setting.
+
+#### Example: Document access
+
+This example demonstrates that enabling `plugins.security.dfm_empty_overrides_all` is beneficial in scenarios where you need specific users to have unrestricted access to documents despite being part of a broader group with restricted access.
+
+**Role A with DLS**: This role is granted to a broad group of users and includes DLS to restrict access to specific documents, as shown in the following permission set:
+
+```
+{
+  "index_permissions": [
+    {
+      "index_patterns": ["example-index"],
+      "dls": "[.. some DLS here ..]",
+      "allowed_actions": ["indices:data/read/search"]
+    }
+  ]
+}
+```
+
+**Role B without DLS:** This role is specifically granted to certain users, such as administrators, and does not include DLS, as shown in the following permission set:
+
+```
+{
+  "index_permissions" : [
+    {
+      "index_patterns" : ["*"],
+      "allowed_actions" : ["indices:data/read/search"]
+    }
+  ]
+}
+```
+{% include copy.html %}
+
+Setting `plugins.security.dfm_empty_overrides_all` to `true` ensures that administrators assigned Role B can override any DLS restrictions imposed by Role A. This allows specific Role B users to access all documents, regardless of the restrictions applied by Role A's DLS restrictions.
+
+#### Example: Search template access
+
+In this example, two roles are defined, one with DLS and another without DLS, granting access to search templates:
+
+**Role A with DLS:**
+
+```
+{
+  "index_permissions": [
+    {
+      "index_patterns": [
+        "example-index"
+      ],
+      "dls": "[.. some DLS here ..]",
+      "allowed_actions": [
+        "indices:data/read/search",
+      ]
+    }
+  ]
+}
+```
+{% include copy.html %}
+
+**Role B, without DLS**, which only grants access to search templates:
+
+```
+{
+  "index_permissions" : [
+    {
+      "index_patterns" : [ "*" ],
+      "allowed_actions" : [ "indices:data/read/search/template" ]
+    }
+  ]
+}
+```
+{% include copy.html %}
+
+When a user has both Role A and Role B permissions, the query results are filtered based on Role A's DLS, even though Role B doesn't use DLS. The DLS settings are retained, and the returned access is appropriately restricted. 
+
+When a user is assigned both Role A and Role B and the `plugins.security.dfm_empty_overrides_all` setting is enabled, Role B's permissions Role B's permissions will override Role A's restrictions, allowing that user to access all documents. This ensures that the role without DLS takes precedence in the search query response.