For [Doc] Alerting plugin RBAC - backend roles usage (#1866)

* for doc issue https://github.com/opensearch-project/documentation-website/issues/1810

Signed-off-by: alicejw <alicejw@amazon.com>

* to add reference link to security plugin section about backend roles

Signed-off-by: alicejw <alicejw@amazon.com>

* more updates and fix link

Signed-off-by: alicejw <alicejw@amazon.com>

* for link to backend roles in Alerting API doc

Signed-off-by: alicejw <alicejw@amazon.com>

* to fine tune the backend_role creation of role1, and role2

Signed-off-by: alicejw <alicejw@amazon.com>

* for tech review feedback updates

Signed-off-by: alicejw <alicejw@amazon.com>

* minor update to remove xref to the monitoring page limit access to backend roles section

Signed-off-by: alicejw <alicejw@amazon.com>

* put notes into a callout

Signed-off-by: alicejw <alicejw@amazon.com>

* for more updates per tech review

Signed-off-by: alicejw <alicejw@amazon.com>

* for doc review feedback updates

Signed-off-by: alicejw <alicejw@amazon.com>

Signed-off-by: alicejw <alicejw@amazon.com>

_monitoring-plugins/alerting/api.md

@@ -99,6 +99,78 @@ If you use a custom webhook for your destination and need to embed JSON in the m
 }
 ```
 
+Optionally, to specify a backend role, you can add the `rbac_roles` parameter and backend role names to the bottom of your create monitor request.
+
+#### Sample request
+
+The following request creates a query-level monitor and provides two backend roles, `role1` and `role2`. The section at the bottom of the request shows the line that specifies the roles with this syntax: `"rbac_roles": ["role1", "role2"]`.
+
+```json
+POST _plugins/_alerting/monitors
+{
+  "type": "monitor",
+  "name": "test-monitor",
+  "monitor_type": "query_level_monitor",
+  "enabled": true,
+  "schedule": {
+    "period": {
+      "interval": 1,
+      "unit": "MINUTES"
+    }
+  },
+  "inputs": [{
+    "search": {
+      "indices": ["movies"],
+      "query": {
+        "size": 0,
+        "aggregations": {},
+        "query": {
+          "bool": {
+            "filter": {
+              "range": {
+                "@timestamp": {
+                  "gte": "{{period_end}}||-1h",
+                  "lte": "{{period_end}}",
+                  "format": "epoch_millis"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }],
+  "triggers": [{
+    "name": "test-trigger",
+    "severity": "1",
+    "condition": {
+      "script": {
+        "source": "ctx.results[0].hits.total.value > 0",
+        "lang": "painless"
+      }
+    },
+    "actions": [{
+      "name": "test-action",
+      "destination_id": "ld7912sBlQ5JUWWFThoW",
+      "message_template": {
+        "source": "This is my message body."
+      },
+      "throttle_enabled": true,
+      "throttle": {
+        "value": 27,
+        "unit": "MINUTES"
+      },
+      "subject_template": {
+        "source": "TheSubject"
+      }
+    }]
+  }],
+  "rbac_roles": ["role1", "role2"]
+}
+```
+
+To learn more about using backend roles to limit access, see [(Advanced) Limit access by backend role]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/#advanced-limit-access-by-backend-role).
+
 #### Sample response
 
 ```json

_monitoring-plugins/alerting/security.md

@@ -42,7 +42,7 @@ If your monitor's trigger has notifications configured, the Alerting plugin cont
 
 Out of the box, the alerting plugin has no concept of ownership. For example, if you have the `cluster:admin/opensearch/alerting/monitor/write` permission, you can edit *all* monitors, regardless of whether you created them. If a small number of trusted users manage your monitors and destinations, this lack of ownership generally isn't a problem. A larger organization might need to segment access by backend role.
 
-First, make sure that your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user).
+First, make sure that your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/). However, if you use the internal user database, you can use the REST API to add them manually with a create user operation. To add a backend role to a create user request, follow the [Create user]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user) instructions in the Security Plugin API documentation.
 
 Next, enable the following setting:
 
@@ -82,3 +82,42 @@ If you only want users to be able to see and modify their own monitors and desti
 ```
 
 Then, use this new role for all alerting users. -->
+
+### Specify RBAC backend roles
+
+You can specify RBAC backend roles when you create or update a monitor with the Alerting API.
+
+In a create monitor scenario, follow these guidelines to specify roles:
+
+User type  | Role is specified by user or not (Y/N) | How to use the RBAC roles
+:--- | :--- | :---
+Admin user | Yes | Use all the specified backend roles to associate to the monitor.
+Regular user | Yes | Use all the specified backend roles from the list of backend roles that the user has permission to use to associate with the monitor.
+Regular user | No | Copy user’s backend roles and associate them to the monitor.
+
+In an update monitor scenario, follow these guidelines to specify roles:
+
+User type  | Role is specified by user or not (Y/N) | How to use the RBAC roles
+:--- | :--- | :---
+Admin user | Yes | Remove all the backend roles associate to the monitor and then use all the specified backend roles associated to the monitor.
+Regular user | Yes | Remove backend roles associated to the monitor that the user has access to, but didn’t specify. Then add all the other specified backend roles from the list of backend roles that the user has permission to use to the monitor.
+Regular user | No | Don’t update the backend roles on the monitor.
+
+- For admin users, an empty list is considered the same as removing all permissions that the user possesses. If a non-admin user passes in an empty list, that will throw an exception, because that is not allowed by non-admin users.
+- If the user tries to associate roles that they don't have permission to use, it will throw an exception.
+{: .note }
+
+To create an RBAC role, follow instructions in the Security Plugin API documentation to [Create role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-role).
+### Create a monitor with an RBAC role
+
+When you create a monitor with the Alerting API, you can specify the role-based access control (RBAC) roles at the bottom of the request body. Use the `rbac_roles` parameter.
+
+The following sample shows the RBAC roles specified by the RBAC parameter:
+
+```json
+... 
+  "rbac_roles": ["role1", "role2"]
+}
+```
+
+To see a full request sample, see [Create a monitor]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/api/#create-a-query-level-monitor).

_security-plugin/access-control/api.md

@@ -434,7 +434,7 @@ PUT _plugins/_security/api/internalusers/<username>
 {
   "password": "kirkpass",
   "opendistro_security_roles": ["maintenance_staff", "weapons"],
-  "backend_roles": ["captains", "starfleet"],
+  "backend_roles": ["role 1", "role 2"],
   "attributes": {
     "attribute1": "value1",
     "attribute2": "value2"