Skip to content

Commit 2f20ae2

Browse files
lcawllcawl
committed
[DOCS] Splits the roles API documentation into multiple pages (#32794)
1 parent cbbb2b7 commit 2f20ae2

11 files changed

+312
-206
lines changed

‎x-pack/docs/build.gradle

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -723,3 +723,17 @@ setups['sensor_prefab_data'] = '''
723723
{"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"}
724724
725725
'''
726+
setups['admin_role'] = '''
727+
- do:
728+
xpack.security.put_role:
729+
name: "my_admin_role"
730+
body: >
731+
{
732+
"cluster": ["all"],
733+
"indices": [
734+
{"names": ["index1", "index2" ], "privileges": ["all"], "field_security" : {"grant" : [ "title", "body" ]}}
735+
],
736+
"run_as": [ "other_user" ],
737+
"metadata" : {"version": 1}
738+
}
739+
'''

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

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,26 @@
22
[[security-api]]
33
== Security APIs
44

5+
You can use the following APIs to perform {security} activities.
6+
57
* <<security-api-authenticate>>
68
* <<security-api-clear-cache>>
79
* <<security-api-privileges>>
8-
* <<security-api-roles>>
910
* <<security-api-role-mapping>>
1011
* <<security-api-ssl>>
1112
* <<security-api-tokens>>
1213
* <<security-api-users>>
1314

15+
include::security/roles.asciidoc[]
16+
1417
include::security/authenticate.asciidoc[]
1518
include::security/change-password.asciidoc[]
1619
include::security/clear-cache.asciidoc[]
20+
include::security/clear-roles-cache.asciidoc[]
21+
include::security/create-roles.asciidoc[]
22+
include::security/delete-roles.asciidoc[]
23+
include::security/get-roles.asciidoc[]
1724
include::security/privileges.asciidoc[]
18-
include::security/roles.asciidoc[]
1925
include::security/role-mapping.asciidoc[]
2026
include::security/ssl.asciidoc[]
2127
include::security/tokens.asciidoc[]

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
[role="xpack"]
2+
[[security-api-clear-role-cache]]
3+
=== Clear roles cache API
4+
5+
Evicts roles from the native role cache.
6+
7+
==== Request
8+
9+
`POST /_xpack/security/role/<name>/_clear_cache`
10+
11+
==== Description
12+
13+
For more information about the native realm, see
14+
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
15+
16+
==== Path Parameters
17+
18+
`name`::
19+
(string) The name of the role.
20+
21+
22+
//==== Request Body
23+
24+
==== Authorization
25+
26+
To use this API, you must have at least the `manage_security` cluster
27+
privilege.
28+
29+
30+
==== Examples
31+
32+
The clear roles cache API evicts roles from the native role cache. For example,
33+
to clear the cache for `my_admin_role`:
34+
35+
[source,js]
36+
--------------------------------------------------
37+
POST /_xpack/security/role/my_admin_role/_clear_cache
38+
--------------------------------------------------
39+
// CONSOLE

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

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
[role="xpack"]
2+
[[security-api-put-role]]
3+
=== Create roles API
4+
5+
Adds roles in the native realm.
6+
7+
==== Request
8+
9+
`POST /_xpack/security/role/<name>` +
10+
11+
`PUT /_xpack/security/role/<name>`
12+
13+
14+
==== Description
15+
16+
The role API is generally the preferred way to manage roles, rather than using
17+
file-based role management. For more information about the native realm, see
18+
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
19+
20+
21+
==== Path Parameters
22+
23+
`name`::
24+
(string) The name of the role.
25+
26+
27+
==== Request Body
28+
29+
The following parameters can be specified in the body of a PUT or POST request
30+
and pertain to adding a role:
31+
32+
`cluster`:: (list) A list of cluster privileges. These privileges define the
33+
cluster level actions that users with this role are able to execute.
34+
35+
`indices`:: (list) A list of indices permissions entries.
36+
`field_security`::: (list) The document fields that the owners of the role have
37+
read access to. For more information, see
38+
{stack-ov}/field-and-document-access-control.html[Setting up field and document level security].
39+
`names` (required)::: (list) A list of indices (or index name patterns) to which the
40+
permissions in this entry apply.
41+
`privileges`(required)::: (list) The index level privileges that the owners of the role
42+
have on the specified indices.
43+
`query`::: A search query that defines the documents the owners of the role have
44+
read access to. A document within the specified indices must match this query in
45+
order for it to be accessible by the owners of the role.
46+
47+
`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys
48+
that begin with `_` are reserved for system usage.
49+
50+
`run_as`:: (list) A list of users that the owners of this role can impersonate.
51+
For more information, see
52+
{stack-ov}/run-as-privilege.html[Submitting requests on behalf of other users].
53+
54+
For more information, see {stack-ov}/defining-roles.html[Defining roles].
55+
56+
57+
==== Authorization
58+
59+
To use this API, you must have at least the `manage_security` cluster
60+
privilege.
61+
62+
63+
==== Examples
64+
65+
The following example adds a role called `my_admin_role`:
66+
67+
[source,js]
68+
--------------------------------------------------
69+
POST /_xpack/security/role/my_admin_role
70+
{
71+
"cluster": ["all"],
72+
"indices": [
73+
{
74+
"names": [ "index1", "index2" ],
75+
"privileges": ["all"],
76+
"field_security" : { // optional
77+
"grant" : [ "title", "body" ]
78+
},
79+
"query": "{\"match\": {\"title\": \"foo\"}}" // optional
80+
}
81+
],
82+
"run_as": [ "other_user" ], // optional
83+
"metadata" : { // optional
84+
"version" : 1
85+
}
86+
}
87+
--------------------------------------------------
88+
// CONSOLE
89+
90+
A successful call returns a JSON structure that shows whether the role has been
91+
created or updated.
92+
93+
[source,js]
94+
--------------------------------------------------
95+
{
96+
"role": {
97+
"created": true <1>
98+
}
99+
}
100+
--------------------------------------------------
101+
// TESTRESPONSE
102+
<1> When an existing role is updated, `created` is set to false.
103+

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

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
[role="xpack"]
2+
[[security-api-delete-role]]
3+
=== Delete roles API
4+
5+
Removes roles in the native realm.
6+
7+
==== Request
8+
9+
`DELETE /_xpack/security/role/<name>`
10+
11+
12+
==== Description
13+
14+
The Roles API is generally the preferred way to manage roles, rather than using
15+
file-based role management. For more information about the native realm, see
16+
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
17+
18+
19+
==== Path Parameters
20+
21+
`name`::
22+
(string) The name of the role.
23+
24+
//==== Request Body
25+
26+
==== Authorization
27+
28+
To use this API, you must have at least the `manage_security` cluster
29+
privilege.
30+
31+
32+
==== Examples
33+
34+
The following example deletes a `my_admin_role` role:
35+
36+
[source,js]
37+
--------------------------------------------------
38+
DELETE /_xpack/security/role/my_admin_role
39+
--------------------------------------------------
40+
// CONSOLE
41+
// TEST[setup:admin_role]
42+
43+
If the role is successfully deleted, the request returns `{"found": true}`.
44+
Otherwise, `found` is set to false.
45+
46+
[source,js]
47+
--------------------------------------------------
48+
{
49+
"found" : true
50+
}
51+
--------------------------------------------------
52+
// TESTRESPONSE

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

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
[role="xpack"]
2+
[[security-api-get-role]]
3+
=== Get roles API
4+
5+
Retrieves roles in the native realm.
6+
7+
==== Request
8+
9+
`GET /_xpack/security/role` +
10+
11+
`GET /_xpack/security/role/<name>` +
12+
13+
==== Description
14+
15+
For more information about the native realm, see
16+
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
17+
18+
==== Path Parameters
19+
20+
`name`::
21+
(string) The name of the role. You can specify multiple roles as a
22+
comma-separated list. If you do not specify this parameter, the API
23+
returns information about all roles.
24+
25+
//==== Request Body
26+
27+
==== Authorization
28+
29+
To use this API, you must have at least the `manage_security` cluster
30+
privilege.
31+
32+
33+
==== Examples
34+
35+
The following example retrieves information about the `my_admin_role` role in
36+
the native realm:
37+
38+
[source,js]
39+
--------------------------------------------------
40+
GET /_xpack/security/role/my_admin_role
41+
--------------------------------------------------
42+
// CONSOLE
43+
// TEST[setup:admin_role]
44+
45+
A successful call returns an array of roles with the JSON representation of the
46+
role. If the role is not defined in the native realm, the request returns 404.
47+
48+
[source,js]
49+
--------------------------------------------------
50+
{
51+
"my_admin_role": {
52+
"cluster" : [ "all" ],
53+
"indices" : [
54+
{
55+
"names" : [ "index1", "index2" ],
56+
"privileges" : [ "all" ],
57+
"field_security" : {
58+
"grant" : [ "title", "body" ]}
59+
}
60+
],
61+
"applications" : [ ],
62+
"run_as" : [ "other_user" ],
63+
"metadata" : {
64+
"version" : 1
65+
},
66+
"transient_metadata": {
67+
"enabled": true
68+
}
69+
}
70+
}
71+
--------------------------------------------------
72+
// TESTRESPONSE
73+
74+
To retrieve all roles, omit the role name:
75+
76+
[source,js]
77+
--------------------------------------------------
78+
GET /_xpack/security/role
79+
--------------------------------------------------
80+
// CONSOLE
81+
// TEST[continued]
82+
83+
NOTE: If single role is requested, that role is returned as the response. When
84+
requesting multiple roles, an object is returned holding the found roles, each
85+
keyed by the relevant role name.
86+

0 commit comments

Comments
 (0)