Skip to content

Commit 57eaca5

Browse files
lcawllcawl
committed
[DOC] Splits role mapping APIs into separate pages (#32797)
1 parent fc5bdbc commit 57eaca5

16 files changed

+487
-418
lines changed

‎docs/reference/redirects.asciidoc

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -526,3 +526,11 @@ native realm:
526526
* <<security-api-enable-user,Enable users>>, <<security-api-disable-user,Disable users>>
527527
* <<security-api-change-password,Change passwords>>
528528
* <<security-api-get-user,Get users>>
529+
530+
[role="exclude",id="security-api-role-mapping"]
531+
=== Role mapping APIs
532+
533+
You can use the following APIs to add, remove, and retrieve role mappings:
534+
535+
* <<security-api-put-role-mapping,Add role mappings>>, <<security-api-delete-role-mapping,Delete role mappings>>
536+
* <<security-api-get-role-mapping,Get role mappings>>

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

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
[[ml-api-definitions]]
33
== Definitions
44

5-
These resource definitions are used in {ml} APIs and in {kib} advanced
6-
job configuration options.
5+
These resource definitions are used in {ml} and {security} APIs and in {kib}
6+
advanced {ml} job configuration options.
77

88
* <<ml-calendar-resource,Calendars>>
99
* <<ml-datafeed-resource,{dfeeds-cap}>>
@@ -12,6 +12,7 @@ job configuration options.
1212
* <<ml-jobstats,Job statistics>>
1313
* <<ml-snapshot-resource,Model snapshots>>
1414
* <<ml-results-resource,Results>>
15+
* <<role-mapping-resources,Role mappings>>
1516
* <<ml-event-resource,Scheduled Events>>
1617

1718
[role="xpack"]
@@ -23,6 +24,8 @@ include::ml/jobresource.asciidoc[]
2324
[role="xpack"]
2425
include::ml/jobcounts.asciidoc[]
2526
[role="xpack"]
27+
include::security/role-mapping-resources.asciidoc[]
28+
[role="xpack"]
2629
include::ml/snapshotresource.asciidoc[]
2730
[role="xpack"]
2831
include::ml/resultsresource.asciidoc[]

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

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ You can use the following APIs to perform {security} activities.
77
* <<security-api-authenticate>>
88
* <<security-api-clear-cache>>
99
* <<security-api-privileges>>
10-
* <<security-api-role-mapping>>
1110
* <<security-api-ssl>>
1211

1312
[float]
@@ -20,6 +19,15 @@ You can use the following APIs to add, remove, and retrieve roles in the native
2019
* <<security-api-clear-role-cache,Clear roles cache>>
2120
* <<security-api-get-role,Get roles>>
2221

22+
[float]
23+
[[security-role-mapping-apis]]
24+
=== Role mappings
25+
26+
You can use the following APIs to add, remove, and retrieve role mappings:
27+
28+
* <<security-api-put-role-mapping,Add role mappings>>, <<security-api-delete-role-mapping,Delete role mappings>>
29+
* <<security-api-get-role-mapping,Get role mappings>>
30+
2331
[float]
2432
[[security-token-apis]]
2533
=== Tokens
@@ -44,17 +52,19 @@ native realm:
4452
include::security/authenticate.asciidoc[]
4553
include::security/change-password.asciidoc[]
4654
include::security/clear-cache.asciidoc[]
55+
include::security/create-role-mappings.asciidoc[]
4756
include::security/clear-roles-cache.asciidoc[]
4857
include::security/create-roles.asciidoc[]
4958
include::security/create-users.asciidoc[]
59+
include::security/delete-role-mappings.asciidoc[]
5060
include::security/delete-roles.asciidoc[]
5161
include::security/delete-tokens.asciidoc[]
5262
include::security/delete-users.asciidoc[]
5363
include::security/disable-users.asciidoc[]
5464
include::security/enable-users.asciidoc[]
65+
include::security/get-role-mappings.asciidoc[]
5566
include::security/get-roles.asciidoc[]
5667
include::security/get-tokens.asciidoc[]
5768
include::security/get-users.asciidoc[]
5869
include::security/privileges.asciidoc[]
59-
include::security/role-mapping.asciidoc[]
6070
include::security/ssl.asciidoc[]

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

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
[role="xpack"]
2+
[[security-api-put-role-mapping]]
3+
=== Add role mappings API
4+
5+
Adds and updates role mappings.
6+
7+
==== Request
8+
9+
`POST /_xpack/security/role_mapping/<name>` +
10+
11+
`PUT /_xpack/security/role_mapping/<name>`
12+
13+
14+
==== Description
15+
16+
Role mappings define which roles are assigned to each user. Each mapping has
17+
_rules_ that identify users and a list of _roles_ that are
18+
granted to those users.
19+
20+
NOTE: This API does not create roles. Rather, it maps users to existing roles.
21+
Roles can be created by using <<security-api-roles, Role Management APIs>> or
22+
{stack-ov}/defining-roles.html#roles-management-file[roles files].
23+
24+
For more information, see
25+
{stack-ov}/mapping-roles.html[Mapping users and groups to roles].
26+
27+
28+
==== Path Parameters
29+
30+
`name`::
31+
(string) The distinct name that identifies the role mapping. The name is
32+
used solely as an identifier to facilitate interaction via the API; it does
33+
not affect the behavior of the mapping in any way.
34+
35+
36+
==== Request Body
37+
38+
The following parameters can be specified in the body of a PUT or POST request
39+
and pertain to adding a role mapping:
40+
41+
`enabled` (required)::
42+
(boolean) Mappings that have `enabled` set to `false` are ignored when role
43+
mapping is performed.
44+
45+
`metadata`::
46+
(object) Additional metadata that helps define which roles are assigned to each
47+
user. Within the `metadata` object, keys beginning with `_` are reserved for
48+
system usage.
49+
50+
`roles` (required)::
51+
(list) A list of roles that are granted to the users that match the role mapping
52+
rules.
53+
54+
`rules` (required)::
55+
(object) The rules that determine which users should be matched by the mapping.
56+
A rule is a logical condition that is expressed by using a JSON DSL. See
57+
<<role-mapping-resources>>.
58+
59+
60+
==== Authorization
61+
62+
To use this API, you must have at least the `manage_security` cluster privilege.
63+
64+
65+
==== Examples
66+
67+
The following example assigns the "user" role to all users:
68+
69+
[source, js]
70+
------------------------------------------------------------
71+
POST /_xpack/security/role_mapping/mapping1
72+
{
73+
"roles": [ "user"],
74+
"enabled": true, <1>
75+
"rules": {
76+
"field" : { "username" : "*" }
77+
},
78+
"metadata" : { <2>
79+
"version" : 1
80+
}
81+
}
82+
------------------------------------------------------------
83+
// CONSOLE
84+
<1> Mappings that have `enabled` set to `false` are ignored when role mapping
85+
is performed.
86+
<2> Metadata is optional.
87+
88+
A successful call returns a JSON structure that shows whether the mapping has
89+
been created or updated.
90+
91+
[source,js]
92+
--------------------------------------------------
93+
{
94+
"role_mapping" : {
95+
"created" : true <1>
96+
}
97+
}
98+
--------------------------------------------------
99+
// TESTRESPONSE
100+
<1> When an existing mapping is updated, `created` is set to false.
101+
102+
The following example assigns the "user" and "admin" roles to specific users:
103+
104+
[source,js]
105+
--------------------------------------------------
106+
POST /_xpack/security/role_mapping/mapping2
107+
{
108+
"roles": [ "user", "admin" ],
109+
"enabled": true,
110+
"rules": {
111+
"field" : { "username" : [ "esadmin01", "esadmin02" ] }
112+
}
113+
}
114+
--------------------------------------------------
115+
// CONSOLE
116+
117+
The following example matches any user where either the username is `esadmin`
118+
or the user is in the `cn=admin,dc=example,dc=com` group:
119+
120+
[source, js]
121+
------------------------------------------------------------
122+
POST /_xpack/security/role_mapping/mapping3
123+
{
124+
"roles": [ "superuser" ],
125+
"enabled": true,
126+
"rules": {
127+
"any": [
128+
{
129+
"field": {
130+
"username": "esadmin"
131+
}
132+
},
133+
{
134+
"field": {
135+
"groups": "cn=admins,dc=example,dc=com"
136+
}
137+
}
138+
]
139+
}
140+
}
141+
------------------------------------------------------------
142+
// CONSOLE
143+
144+
The following example matches users who authenticated against a specific realm:
145+
[source, js]
146+
------------------------------------------------------------
147+
POST /_xpack/security/role_mapping/mapping4
148+
{
149+
"roles": [ "ldap-user" ],
150+
"enabled": true,
151+
"rules": {
152+
"field" : { "realm.name" : "ldap1" }
153+
}
154+
}
155+
------------------------------------------------------------
156+
// CONSOLE
157+
158+
The following example matches users within a specific LDAP sub-tree:
159+
160+
[source, js]
161+
------------------------------------------------------------
162+
POST /_xpack/security/role_mapping/mapping5
163+
{
164+
"roles": [ "example-user" ],
165+
"enabled": true,
166+
"rules": {
167+
"field" : { "dn" : "*,ou=subtree,dc=example,dc=com" }
168+
}
169+
}
170+
------------------------------------------------------------
171+
// CONSOLE
172+
173+
The following example matches users within a particular LDAP sub-tree in a
174+
specific realm:
175+
176+
[source, js]
177+
------------------------------------------------------------
178+
POST /_xpack/security/role_mapping/mapping6
179+
{
180+
"roles": [ "ldap-example-user" ],
181+
"enabled": true,
182+
"rules": {
183+
"all": [
184+
{ "field" : { "dn" : "*,ou=subtree,dc=example,dc=com" } },
185+
{ "field" : { "realm.name" : "ldap1" } }
186+
]
187+
}
188+
}
189+
------------------------------------------------------------
190+
// CONSOLE
191+
192+
The rules can be more complex and include wildcard matching. For example, the
193+
following mapping matches any user where *all* of these conditions are met:
194+
195+
- the _Distinguished Name_ matches the pattern `*,ou=admin,dc=example,dc=com`,
196+
or the username is `es-admin`, or the username is `es-system`
197+
- the user in in the `cn=people,dc=example,dc=com` group
198+
- the user does not have a `terminated_date`
199+
200+
201+
[source, js]
202+
------------------------------------------------------------
203+
POST /_xpack/security/role_mapping/mapping7
204+
{
205+
"roles": [ "superuser" ],
206+
"enabled": true,
207+
"rules": {
208+
"all": [
209+
{
210+
"any": [
211+
{
212+
"field": {
213+
"dn": "*,ou=admin,dc=example,dc=com"
214+
}
215+
},
216+
{
217+
"field": {
218+
"username": [ "es-admin", "es-system" ]
219+
}
220+
}
221+
]
222+
},
223+
{
224+
"field": {
225+
"groups": "cn=people,dc=example,dc=com"
226+
}
227+
},
228+
{
229+
"except": {
230+
"field": {
231+
"metadata.terminated_date": null
232+
}
233+
}
234+
}
235+
]
236+
}
237+
}
238+
------------------------------------------------------------
239+
// CONSOLE

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
[role="xpack"]
2+
[[security-api-delete-role-mapping]]
3+
=== Delete role mappings API
4+
5+
Removes role mappings.
6+
7+
==== Request
8+
9+
`DELETE /_xpack/security/role_mapping/<name>`
10+
11+
==== Description
12+
13+
Role mappings define which roles are assigned to each user. For more information,
14+
see {stack-ov}/mapping-roles.html[Mapping users and groups to roles].
15+
16+
==== Path Parameters
17+
18+
`name`::
19+
(string) The distinct name that identifies the role mapping. The name is
20+
used solely as an identifier to facilitate interaction via the API; it does
21+
not affect the behavior of the mapping in any way.
22+
23+
//==== Request Body
24+
25+
==== Authorization
26+
27+
To use this API, you must have at least the `manage_security` cluster privilege.
28+
29+
30+
==== Examples
31+
32+
The following example delete a role mapping:
33+
34+
[source,js]
35+
--------------------------------------------------
36+
DELETE /_xpack/security/role_mapping/mapping1
37+
--------------------------------------------------
38+
// CONSOLE
39+
// TEST[setup:role_mapping]
40+
41+
If the mapping is successfully deleted, the request returns `{"found": true}`.
42+
Otherwise, `found` is set to false.
43+
44+
[source,js]
45+
--------------------------------------------------
46+
{
47+
"found" : true
48+
}
49+
--------------------------------------------------
50+
// TESTRESPONSE

0 commit comments

Comments
 (0)