Adding explanation for editing permissions 20230825 (#6606)

* adding explination for editing permissions Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com> * changed to a h3 to see if review dog will accept Signed-off-by: leanne.laceybyrne@eliatra.com <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> * Updates to both the users roles and DLS sections to reflect need to add edit DLS section Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com> * updating after reviewdog comments Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com> * updating roles in OpenSearch updates Signed-off-by: leanne.laceybyrne@eliatra.com <leanne.laceybyrne@eliatra.com> * Apply suggestions from code review Updates following review Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Nathan Bower <nbower@amazon.com> 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> * Update _security/access-control/document-level-security.md Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: leanneeliatra <131779422+leanneeliatra@users.noreply.github.com> --------- Signed-off-by: leanne.laceybyrne@eliatra.com <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: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
opensearch-project · Mar 28, 2024 · 6f8261b · 6f8261b
1 parent 13a3537
commit 6f8261b
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 24 deletions.
diff --git a/_security/access-control/document-level-security.md b/_security/access-control/document-level-security.md
@@ -10,30 +10,31 @@ redirect_from:
 
 # Document-level security (DLS)
 
-Document-level security lets you restrict a role to a subset of documents in an index. The easiest way to get started with document- and field-level security is to open OpenSearch Dashboards and choose **Security**. Then choose **Roles**, create a new role, and review the **Index permissions** section.
-
-![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png)
-
-
-## Simple roles
-
-Document-level security uses the OpenSearch query DSL to define which documents a role grants access to. In OpenSearch Dashboards, choose an index pattern and provide a query in the **Document level security** section:
-
-```json
-{
-  "bool": {
-    "must": {
-      "match": {
-        "genres": "Comedy"
-      }
-    }
-  }
-}
-```
-
-This query specifies that for the role to have access to a document, its `genres` field must include `Comedy`.
-
-A typical request to the `_search` API includes `{ "query": { ... } }` around the query, but in this case, you only need to specify the query itself.
+Document-level security lets you restrict a role to a subset of documents in an index.
+For more information about OpenSearch users and roles, see the [documentation](https://opensearch.org/docs/latest/security/access-control/users-roles/#create-roles).
+
+Use the following steps to get started with document-level and field-level security:
+1. Open OpenSearch Dashboards.
+2. Choose **Security** > **Roles**.
+3. Select **Create Role** and provide a name for the role.
+4. Review the **Index permissions** section and any necessary [index permissions](https://opensearch.org/docs/latest/security/access-control/permissions/) for the role. 
+5. Add document-level security, with the addition of a domain-specific language (DSL) query in the `Document level security - optional` section. A typical request sent to the `_search` API includes `{ "query": { ... } }` around the query, but with document-level security in OpenSearch Dashboards, you only need to specify the query itself. For example, the following DSL query specifies that for the new role to have access to a document, the query's `genres` field must include `Comedy`:
+
+   ```json
+   {
+     "bool": {
+       "must": {
+         "match": {
+           "genres": "Comedy"
+         }
+       }
+     }
+   }
+   ```
+
+   - ![Document- and field-level security screen in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/security-dls.png)
+
+## Updating roles by accessing the REST API 
 
 In the REST API, you provide the query as a string, so you must escape your quotes. This role allows a user to read any document in any index with the field `public` set to `true`:
 

diff --git a/_security/access-control/users-roles.md b/_security/access-control/users-roles.md
@@ -14,6 +14,23 @@ The Security plugin includes an internal user database. Use this database in pla
 
 Roles are the core way of controlling access to your cluster. Roles contain any combination of cluster-wide permissions, index-specific permissions, document- and field-level security, and tenants. Then you map users to these roles so that users gain those permissions.
 
+## Creating and editing OpenSearch roles
+
+You can update OpenSearch by using one of the following methods.
+
+### Using the API
+
+You can send HTTP requests to OpenSearch-provided endpoints to update security roles, permissions, and associated settings. This method offers granular control and automation capabilities for managing roles.
+
+### Using the UI (OpenSearch Dashboards)
+
+OpenSearch Dashboards provides a user-friendly interface for managing roles. Roles, permissions, and document-level security settings are configured in the Security section within OpenSearch Dashboards. When updating roles through the UI, OpenSearch Dashboards calls the API in the background to implement the changes.
+
+### Editing the `roles.yml` file
+
+If you want more granular control of your security configuration, you can edit roles and their associated permissions in the `roles.yml` file. This method provides direct access to the underlying configuration and can be version controlled for use in collaborative development environments.
+For more information about creating roles, see the [Create roles][https://opensearch.org/docs/latest/security/access-control/users-roles/#create-roles) documentation.
+
 Unless you need to create new [reserved or hidden users]({{site.url}}{{site.baseurl}}/security/access-control/api/#reserved-and-hidden-resources), we **highly** recommend using OpenSearch Dashboards or the REST API to create new users, roles, and role mappings. The `.yml` files are for initial setup, not ongoing use.
 {: .warning }
 
@@ -75,6 +92,24 @@ See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#roles
 
 See [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role).
 
+## Edit roles
+
+You can edit roles using one of the following methods.
+
+### OpenSearch Dashboards
+
+1. Choose **Security** > **Roles**. In the **Create role** section, select **Explore existing roles**. 
+1. Select the role you want to edit. 
+1. Choose **edit role**. Make any necessary updates to the role.
+1. To save your changes, select **Update**.
+
+### roles.yml
+
+See [YAML files]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#rolesyml).
+
+### REST API
+
+See [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role).
 
 ## Map users to roles