From c0c0299fd5e99ea7151eac42c4172025f4e3bf9b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 1 Mar 2024 22:59:12 +0000 Subject: [PATCH] Add 'DLS and multiple roles' section to DLS topic (#6408) * explaination of setting plugins.security.dfm_empty_overrides_all: true Signed-off-by: leanne.laceybyrne@eliatra.com * datadog grammer corrected in documentation Signed-off-by: leanne.laceybyrne@eliatra.com * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> * adding more examples of setting for dsl to make it clearer Signed-off-by: leanne.laceybyrne@eliatra.com * small edits to fix spacing in previous commit Signed-off-by: leanne.laceybyrne@eliatra.com * Update _security/access-control/document-level-security.md Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> * reviewdog fixes Signed-off-by: leanne.laceybyrne@eliatra.com * Formatting edits. Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Update document-level-security.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --------- Signed-off-by: leanne.laceybyrne@eliatra.com Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: leanne.laceybyrne@eliatra.com Co-authored-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Nathan Bower (cherry picked from commit 93d07a0dcba48d2b2c433347ec6dedcb6fd5e762) Signed-off-by: github-actions[bot] --- .../access-control/document-level-security.md | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md index d1c275119b..3f2049a1e2 100644 --- 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.