Adding explanation for editing permissions 20230825

_security/access-control/document-level-security.md

@@ -10,30 +10,33 @@ 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 users and roles in OpenSearch[, see the documentation.](https://opensearch.org/docs/latest/security/access-control/users-roles/#create-roles)
+
+The easiest way to get started with document- and field-level security is:
+1. Open OpenSearch Dashboards 
+2. Choose **Security**
+3. Choose **Roles** 
+4. Create a new role
+5. Review the **Index permissions** section
+6. Add document-level security with the addition of a DSL query to the `Document level security - optional` section
+   - For example, the following DSL could be added in the `Document level security - optional` text box.
+   - 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.
+   ```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`:
 

_security/access-control/users-roles.md

@@ -14,6 +14,20 @@
 
 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 - Overview
+
+OpenSearch roles can be updated using various methods, the three methods to add or edit roles are as follows.
+
+### Using the API:
+Users can make HTTP requests to endpoints provided by OpenSearch 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. Navigate to the Security section within OpenSearch Dashboard where the roles, permissions, and document-level security settings can be configured. When updating the roles via the UI, the UI calls the API in the background to implement these changes.
+
+### Editing the YAML Configuration File:
+For users comfortable with configuration files and prefer a text-based approach, editing the YAML configuration file directly is an option. Roles and their associated permissions can be defined or modified within the roles.yml file. This method provides direct access to the underlying configuration and can be version-controlled for collaborative development environments.
+More information on **Creating Roles** can be found in the [Create Roles documentation][https://opensearch.org/docs/latest/security/access-control/users-roles/#create-roles)
+
 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 +89,23 @@
 
 See [Create role]({{site.url}}{{site.baseurl}}/security/access-control/api/#create-role).
 
+## Edit Roles
+
+### OpenSearch Dashboards
+
+1. Choose **Security**, **Roles**, and under **Create role**, select **Explore existing roles**. 
+1. Given you are logged in with the correct admin permissions for editing the role, select the role from the list you would like to edit. 
+1. Choose 'edit role' on the top right 
+1. Update the role as required.
+1. Choose **Update** to save 
+
+### 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