Browse Source

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

Lisa Cawley 7 years ago
parent
commit
c5de9ec79d

+ 14 - 0
x-pack/docs/build.gradle

@@ -722,3 +722,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}
+          }
+'''

+ 8 - 2
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[]

+ 39 - 0
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

+ 102 - 0
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.

+ 53 - 0
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
+

+ 85 - 0
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.

+ 6 - 202
x-pack/docs/en/rest-api/security/roles.asciidoc

@@ -1,205 +1,9 @@
-[role="xpack"]
+[float]
 [[security-api-roles]]
-=== Role Management APIs
+=== Roles
 
-The Roles API enables you to add, remove, and retrieve roles in the `native`
-realm.
+You can use the following APIs to add, remove, and retrieve roles in the native realm:
 
-==== Request
-
-`GET /_xpack/security/role` +
-
-`GET /_xpack/security/role/<name>` +
-
-`DELETE /_xpack/security/role/<name>` +
-
-`POST /_xpack/security/role/<name>/_clear_cache` +
-
-`POST /_xpack/security/role/<name>` +
-
-`PUT /_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, see
-{xpack-ref}/authorization.html[Configuring Role-based Access Control].
-
-
-==== Path Parameters
-
-`name`::
-  (string) The name of the role. If you do not specify this parameter, the
-  Get Roles API returns information about all roles.
-
-
-==== 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
-{xpack-ref}/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
-{xpack-ref}/run-as-privilege.html[Submitting Requests on Behalf of Other Users].
-
-For more information, see {xpack-ref}/defining-roles.html[Defining Roles].
-
-
-==== Authorization
-
-To use this API, you must have at least the `manage_security` cluster
-privilege.
-
-
-==== Examples
-
-[[security-api-put-role]]
-To add a role, submit a PUT or POST request to the `/_xpack/security/role/<rolename>`
-endpoint:
-
-[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.
-
-[[security-api-get-role]]
-To retrieve a role from the `native` Security realm, issue a GET request to the
-`/_xpack/security/role/<rolename>` endpoint:
-
-[source,js]
---------------------------------------------------
-GET /_xpack/security/role/my_admin_role
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-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 404s.
-
-[source,js]
---------------------------------------------------
-{
-  "my_admin_role": {
-    "cluster" : [ "all" ],
-    "indices" : [ {
-      "names" : [ "index1", "index2" ],
-      "privileges" : [ "all" ],
-      "field_security" : {
-        "grant" : [ "title", "body" ]
-      },
-      "query" : "{\"match\": {\"title\": \"foo\"}}"
-    } ],
-    "applications" : [ ],
-    "run_as" : [ "other_user" ],
-    "metadata" : {
-      "version" : 1
-    },
-    "transient_metadata": {
-      "enabled": true
-    }
-  }
-}
---------------------------------------------------
-// TESTRESPONSE
-
-You can specify multiple roles as a comma-separated list. To retrieve all roles,
-omit the role name.
-
-[source,js]
---------------------------------------------------
-# Retrieve roles "r1", "r2", and "my_admin_role"
-GET /_xpack/security/role/r1,r2,my_admin_role
-
-# Retrieve all roles
-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.
-
-[[security-api-delete-role]]
-To delete a role, submit a DELETE request to the `/_xpack/security/role/<rolename>`
-endpoint:
-
-[source,js]
---------------------------------------------------
-DELETE /_xpack/security/role/my_admin_role
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-If the role is successfully deleted, the request returns `{"found": true}`.
-Otherwise, `found` is set to false.
-
-[source,js]
---------------------------------------------------
-{
-  "found" : true
-}
---------------------------------------------------
-// TESTRESPONSE
-
-[[security-api-clear-role-cache]]
-The Clear Roles Cache API evicts roles from the native role cache. To clear the
-cache for a role, submit a POST request `/_xpack/security/role/<rolename>/_clear_cache`
-endpoint:
-
-[source,js]
---------------------------------------------------
-POST /_xpack/security/role/my_admin_role/_clear_cache
---------------------------------------------------
-// CONSOLE
+* <<security-api-put-role,Create role>>, <<security-api-delete-role,Delete role>>
+* <<security-api-clear-role-cache,Clear roles cache>>
+* <<security-api-get-role,Get roles>>

+ 1 - 1
x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.clear_cached_roles.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.clear_cached_roles": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html#security-api-clear-role-cache",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-role-cache.html",
     "methods": [ "POST" ],
     "url": {
       "path": "/_xpack/security/role/{name}/_clear_cache",

+ 1 - 1
x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.delete_role.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.delete_role": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html#security-api-delete-role",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-delete-role.html",
     "methods": [ "DELETE" ],
     "url": {
       "path": "/_xpack/security/role/{name}",

+ 1 - 1
x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.get_role.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.get_role": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html#security-api-get-role",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-role.html",
     "methods": [ "GET" ],
     "url": {
       "path": "/_xpack/security/role/{name}",

+ 1 - 1
x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.put_role.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.put_role": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-roles.html#security-api-put-role",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-role.html",
     "methods": [ "PUT", "POST" ],
     "url": {
       "path": "/_xpack/security/role/{name}",