[DOCS] Splits the roles API documentation into multiple pages (#32794)

x-pack/docs/build.gradle

@@ -723,3 +723,17 @@ setups['sensor_prefab_data'] = '''
           {"node.terms.value":"c","temperature.sum.value":202.0,"temperature.max.value":202.0,"timestamp.date_histogram.time_zone":"UTC","temperature.min.value":202.0,"timestamp.date_histogram._count":1,"timestamp.date_histogram.interval":"1h","_rollup.computed":["temperature.sum","temperature.min","voltage.avg","temperature.max","node.terms","timestamp.date_histogram"],"voltage.avg.value":4.0,"node.terms._count":1,"_rollup.version":1,"timestamp.date_histogram.timestamp":1516294800000,"voltage.avg._count":1.0,"_rollup.id":"sensor"}
 
 '''
+setups['admin_role'] = '''
+  - do:
+      xpack.security.put_role:
+        name: "my_admin_role"
+        body: >
+          {
+            "cluster": ["all"],
+            "indices": [
+              {"names": ["index1", "index2" ], "privileges": ["all"], "field_security" : {"grant" : [ "title", "body" ]}}
+              ],
+            "run_as": [ "other_user" ],
+            "metadata" : {"version": 1}
+          }
+'''

x-pack/docs/en/rest-api/security.asciidoc

@@ -2,20 +2,26 @@
 [[security-api]]
 == Security APIs
 
+You can use the following APIs to perform {security} activities.
+
 * <<security-api-authenticate>>
 * <<security-api-clear-cache>>
 * <<security-api-privileges>>
-* <<security-api-roles>>
 * <<security-api-role-mapping>>
 * <<security-api-ssl>>
 * <<security-api-tokens>>
 * <<security-api-users>>
 
+include::security/roles.asciidoc[]
+
 include::security/authenticate.asciidoc[]
 include::security/change-password.asciidoc[]
 include::security/clear-cache.asciidoc[]
+include::security/clear-roles-cache.asciidoc[]
+include::security/create-roles.asciidoc[]
+include::security/delete-roles.asciidoc[]
+include::security/get-roles.asciidoc[]
 include::security/privileges.asciidoc[]
-include::security/roles.asciidoc[]
 include::security/role-mapping.asciidoc[]
 include::security/ssl.asciidoc[]
 include::security/tokens.asciidoc[]

x-pack/docs/en/rest-api/security/clear-roles-cache.asciidoc

@@ -0,0 +1,39 @@
+[role="xpack"]
+[[security-api-clear-role-cache]]
+=== Clear roles cache API
+
+Evicts roles from the native role cache. 
+
+==== Request
+
+`POST /_xpack/security/role/<name>/_clear_cache` 
+
+==== Description
+
+For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+
+==== Path Parameters
+
+`name`::
+  (string) The name of the role. 
+
+
+//==== Request Body
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster
+privilege.
+
+
+==== Examples
+
+The clear roles cache API evicts roles from the native role cache. For example, 
+to clear the cache for `my_admin_role`:
+
+[source,js]
+--------------------------------------------------
+POST /_xpack/security/role/my_admin_role/_clear_cache
+--------------------------------------------------
+// CONSOLE

x-pack/docs/en/rest-api/security/create-roles.asciidoc

@@ -0,0 +1,102 @@
+[role="xpack"]
+[[security-api-put-role]]
+=== Create roles API
+
+Adds roles in the native realm.
+
+==== Request
+
+`POST /_xpack/security/role/<name>` +
+
+`PUT /_xpack/security/role/<name>`
+
+
+==== Description
+
+The role API is generally the preferred way to manage roles, rather than using
+file-based role management. For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+
+
+==== Path Parameters
+
+`name`::
+  (string) The name of the role.
+
+
+==== Request Body
+
+The following parameters can be specified in the body of a PUT or POST request
+and pertain to adding a role:
+
+`cluster`:: (list) A list of cluster privileges. These privileges define the
+cluster level actions that users with this role are able to execute.
+
+`indices`:: (list) A list of indices permissions entries.
+`field_security`::: (list) The document fields that the owners of the role have
+read access to. For more information, see
+{stack-ov}/field-and-document-access-control.html[Setting up field and document level security].
+`names` (required)::: (list) A list of indices (or index name patterns) to which the
+permissions in this entry apply.
+`privileges`(required)::: (list) The index level privileges that the owners of the role
+have on the specified indices.
+`query`::: A search query that defines the documents the owners of the role have
+read access to. A document within the specified indices must match this query in
+order for it to be accessible by the owners of the role.
+
+`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys
+that begin with `_` are reserved for system usage.
+
+`run_as`:: (list) A list of users that the owners of this role can impersonate.
+For more information, see
+{stack-ov}/run-as-privilege.html[Submitting requests on behalf of other users].
+
+For more information, see {stack-ov}/defining-roles.html[Defining roles].
+
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster
+privilege.
+
+
+==== Examples
+
+The following example adds a role called `my_admin_role`:
+
+[source,js]
+--------------------------------------------------
+POST /_xpack/security/role/my_admin_role
+{
+  "cluster": ["all"],
+  "indices": [
+    {
+      "names": [ "index1", "index2" ],
+      "privileges": ["all"],
+      "field_security" : { // optional
+        "grant" : [ "title", "body" ]
+      },
+      "query": "{\"match\": {\"title\": \"foo\"}}" // optional
+    }
+  ],
+  "run_as": [ "other_user" ], // optional
+  "metadata" : { // optional
+    "version" : 1
+  }
+}
+--------------------------------------------------
+// CONSOLE
+
+A successful call returns a JSON structure that shows whether the role has been
+created or updated.
+
+[source,js]
+--------------------------------------------------
+{
+  "role": {
+    "created": true <1>
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE
+<1> When an existing role is updated, `created` is set to false.

x-pack/docs/en/rest-api/security/delete-roles.asciidoc

@@ -0,0 +1,53 @@
+[role="xpack"]
+[[security-api-delete-role]]
+=== Delete roles API
+
+Removes roles in the native realm.
+
+==== Request
+
+`DELETE /_xpack/security/role/<name>` 
+
+
+==== Description
+
+The Roles API is generally the preferred way to manage roles, rather than using
+file-based role management. For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+
+
+==== Path Parameters
+
+`name`::
+  (string) The name of the role. 
+
+//==== Request Body
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster
+privilege.
+
+
+==== Examples
+
+The following example deletes a `my_admin_role` role:
+
+[source,js]
+--------------------------------------------------
+DELETE /_xpack/security/role/my_admin_role
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:admin_role]
+
+If the role is successfully deleted, the request returns `{"found": true}`.
+Otherwise, `found` is set to false.
+
+[source,js]
+--------------------------------------------------
+{
+  "found" : true
+}
+--------------------------------------------------
+// TESTRESPONSE
+

x-pack/docs/en/rest-api/security/get-roles.asciidoc

@@ -0,0 +1,85 @@
+[role="xpack"]
+[[security-api-get-role]]
+=== Get roles API
+
+Retrieves roles in the native realm.
+
+==== Request
+
+`GET /_xpack/security/role` +
+
+`GET /_xpack/security/role/<name>` +
+
+==== Description
+
+For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+
+==== Path Parameters
+
+`name`::
+  (string) The name of the role. You can specify multiple roles as a 
+  comma-separated list. If you do not specify this parameter, the API 
+  returns information about all roles.
+
+//==== Request Body
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster
+privilege.
+
+
+==== Examples
+
+The following example retrieves information about the `my_admin_role` role in 
+the native realm:
+
+[source,js]
+--------------------------------------------------
+GET /_xpack/security/role/my_admin_role
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:admin_role]
+
+A successful call returns an array of roles with the JSON representation of the
+role. If the role is not defined in the native realm, the request returns 404.
+
+[source,js]
+--------------------------------------------------
+{
+  "my_admin_role": {
+    "cluster" : [ "all" ],
+    "indices" : [
+      {
+        "names" : [ "index1", "index2" ],
+        "privileges" : [ "all" ],
+        "field_security" : { 
+          "grant" : [ "title", "body" ]}
+      }   
+    ],
+    "applications" : [ ],
+    "run_as" : [ "other_user" ],
+    "metadata" : {
+      "version" : 1
+    },
+    "transient_metadata": {
+      "enabled": true
+    }
+  }  
+}
+--------------------------------------------------
+// TESTRESPONSE
+
+To retrieve all roles, omit the role name:
+
+[source,js]
+--------------------------------------------------
+GET /_xpack/security/role
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+NOTE: If single role is requested, that role is returned as the response. When 
+requesting multiple roles, an object is returned holding the found roles, each 
+keyed by the relevant role name.