Skip to content

Commit 532d552

Browse files
lcawllcawl
authored
[DOCS] Splits the users API documentation into multiple pages (elastic#32825)
1 parent fb1c399 commit 532d552

15 files changed

+375
-239
lines changed

‎docs/reference/redirects.asciidoc

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -520,3 +520,14 @@ You can use the following APIs to create and invalidate bearer tokens for access
520520
without requiring basic authentication:
521521

522522
* <<security-api-get-token,Get token>>, <<security-api-invalidate-token,Invalidate token>>
523+
524+
[role="exclude",id="security-api-users"]
525+
=== User Management APIs
526+
527+
You can use the following APIs to create, read, update, and delete users from the
528+
native realm:
529+
530+
* <<security-api-put-user,Create users>>, <<security-api-delete-user,Delete users>>
531+
* <<security-api-enable-user,Enable users>>, <<security-api-disable-user,Disable users>>
532+
* <<security-api-change-password,Change passwords>>
533+
* <<security-api-get-user,Get users>>

‎x-pack/docs/build.gradle

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -736,3 +736,16 @@ setups['admin_role'] = '''
736736
"metadata" : {"version": 1}
737737
}
738738
'''
739+
setups['jacknich_user'] = '''
740+
- do:
741+
xpack.security.put_user:
742+
username: "jacknich"
743+
body: >
744+
{
745+
"password" : "test-password",
746+
"roles" : [ "admin", "other_role1" ],
747+
"full_name" : "Jack Nicholson",
748+
"email" : "[email protected]",
749+
"metadata" : { "intelligence" : 7 }
750+
}
751+
'''

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

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ You can use the following APIs to perform {security} activities.
99
* <<security-api-privileges>>
1010
* <<security-api-role-mapping>>
1111
* <<security-api-ssl>>
12-
* <<security-api-users>>
1312

1413
[float]
1514
[[security-role-apis]]
@@ -30,16 +29,32 @@ without requiring basic authentication:
3029

3130
* <<security-api-get-token,Get token>>, <<security-api-invalidate-token,Invalidate token>>
3231

32+
[float]
33+
[[security-user-apis]]
34+
=== Users
35+
36+
You can use the following APIs to create, read, update, and delete users from the
37+
native realm:
38+
39+
* <<security-api-put-user,Create users>>, <<security-api-delete-user,Delete users>>
40+
* <<security-api-enable-user,Enable users>>, <<security-api-disable-user,Disable users>>
41+
* <<security-api-change-password,Change passwords>>
42+
* <<security-api-get-user,Get users>>
43+
3344
include::security/authenticate.asciidoc[]
3445
include::security/change-password.asciidoc[]
3546
include::security/clear-cache.asciidoc[]
3647
include::security/clear-roles-cache.asciidoc[]
3748
include::security/create-roles.asciidoc[]
49+
include::security/create-users.asciidoc[]
3850
include::security/delete-roles.asciidoc[]
3951
include::security/delete-tokens.asciidoc[]
52+
include::security/delete-users.asciidoc[]
53+
include::security/disable-users.asciidoc[]
54+
include::security/enable-users.asciidoc[]
4055
include::security/get-roles.asciidoc[]
4156
include::security/get-tokens.asciidoc[]
57+
include::security/get-users.asciidoc[]
4258
include::security/privileges.asciidoc[]
4359
include::security/role-mapping.asciidoc[]
4460
include::security/ssl.asciidoc[]
45-
include::security/users.asciidoc[]

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

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
[role="xpack"]
22
[[security-api-change-password]]
3-
=== Change Password API
3+
=== Change passwords API
44

5-
The Change Password API enables you to submit a request to change the password
6-
of a user.
5+
Changes the passwords of users in the native realm.
76

87
==== Request
98

@@ -12,6 +11,15 @@ of a user.
1211
`POST _xpack/security/user/<username>/_password`
1312

1413

14+
==== Description
15+
16+
You can use the <<security-api-put-user,create user API>> to update everything
17+
but a user's `username` and `password`. This API changes a user's password.
18+
19+
For more information about the native realm, see
20+
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
21+
22+
1523
==== Path Parameters
1624

1725
`username`::
@@ -33,16 +41,17 @@ privilege can change passwords of other users.
3341

3442
==== Examples
3543

36-
The following example updates the password for the `elastic` user:
44+
The following example updates the password for the `jacknich` user:
3745

3846
[source,js]
3947
--------------------------------------------------
40-
POST _xpack/security/user/elastic/_password
48+
POST /_xpack/security/user/jacknich/_password
4149
{
42-
"password": "x-pack-test-password"
50+
"password" : "s3cr3t"
4351
}
4452
--------------------------------------------------
4553
// CONSOLE
54+
// TEST[setup:jacknich_user]
4655

4756
A successful call returns an empty JSON structure.
4857

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

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
[role="xpack"]
2+
[[security-api-put-user]]
3+
=== Create users API
4+
5+
Creates and updates users in the native realm. These users are commonly referred
6+
to as _native users_.
7+
8+
9+
==== Request
10+
11+
`POST /_xpack/security/user/<username>` +
12+
13+
`PUT /_xpack/security/user/<username>`
14+
15+
16+
==== Description
17+
18+
When updating a user, you can update everything but its `username` and `password`.
19+
To change a user's password, use the
20+
<<security-api-change-password, change password API>>.
21+
22+
For more information about the native realm, see
23+
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
24+
25+
==== Path Parameters
26+
27+
`username` (required)::
28+
(string) An identifier for the user.
29+
+
30+
--
31+
[[username-validation]]
32+
NOTE: Usernames must be at least 1 and no more than 1024 characters. They can
33+
contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and
34+
printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block]. Leading or trailing whitespace is not allowed.
35+
36+
--
37+
38+
39+
==== Request Body
40+
41+
The following parameters can be specified in the body of a POST or PUT request:
42+
43+
`enabled`::
44+
(boolean) Specifies whether the user is enabled. The default value is `true`.
45+
46+
`email`::
47+
(string) The email of the user.
48+
49+
`full_name`::
50+
(string) The full name of the user.
51+
52+
`metadata`::
53+
(object) Arbitrary metadata that you want to associate with the user.
54+
55+
`password` (required)::
56+
(string) The user's password. Passwords must be at least 6 characters long.
57+
58+
`roles` (required)::
59+
(list) A set of roles the user has. The roles determine the user's access
60+
permissions. To create a user without any roles, specify an empty list: `[]`.
61+
62+
63+
==== Authorization
64+
65+
To use this API, you must have at least the `manage_security` cluster privilege.
66+
67+
68+
==== Examples
69+
70+
The following example creates a user `jacknich`:
71+
72+
[source,js]
73+
--------------------------------------------------
74+
POST /_xpack/security/user/jacknich
75+
{
76+
"password" : "j@rV1s",
77+
"roles" : [ "admin", "other_role1" ],
78+
"full_name" : "Jack Nicholson",
79+
"email" : "[email protected]",
80+
"metadata" : {
81+
"intelligence" : 7
82+
}
83+
}
84+
--------------------------------------------------
85+
// CONSOLE
86+
87+
A successful call returns a JSON structure that shows whether the user has been
88+
created or updated.
89+
90+
[source,js]
91+
--------------------------------------------------
92+
{
93+
"user": {
94+
"created" : true <1>
95+
}
96+
}
97+
--------------------------------------------------
98+
// TESTRESPONSE
99+
<1> When an existing user is updated, `created` is set to false.
100+
101+
After you add a user, requests from that user can be authenticated. For example:
102+
103+
[source,shell]
104+
--------------------------------------------------
105+
curl -u jacknich:j@rV1s http://localhost:9200/_cluster/health
106+
--------------------------------------------------
107+
// NOTCONSOLE

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

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
[role="xpack"]
2+
[[security-api-delete-user]]
3+
=== Delete users API
4+
5+
Deletes users from the native realm.
6+
7+
==== Request
8+
9+
`DELETE /_xpack/security/user/<username>`
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+
`username` (required)::
19+
(string) An identifier for the user.
20+
21+
//==== Request Body
22+
23+
==== Authorization
24+
25+
To use this API, you must have at least the `manage_security` cluster privilege.
26+
27+
28+
==== Examples
29+
30+
The following example deletes the user `jacknich`:
31+
32+
[source,js]
33+
--------------------------------------------------
34+
DELETE /_xpack/security/user/jacknich
35+
--------------------------------------------------
36+
// CONSOLE
37+
// TEST[setup:jacknich_user]
38+
39+
If the user is successfully deleted, the request returns `{"found": true}`.
40+
Otherwise, `found` is set to false.
41+
42+
[source,js]
43+
--------------------------------------------------
44+
{
45+
"found" : true
46+
}
47+
--------------------------------------------------
48+
// TESTRESPONSE

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
[role="xpack"]
2+
[[security-api-disable-user]]
3+
=== Disable users API
4+
5+
Disables users in the native realm.
6+
7+
8+
==== Request
9+
10+
`PUT /_xpack/security/user/<username>/_disable`
11+
12+
13+
==== Description
14+
15+
By default, when you create users, they are enabled. You can use this API to
16+
revoke a user's access to {es}. To re-enable a user, there is an
17+
<<security-api-enable-user,enable users API>>.
18+
19+
For more information about the native realm, see
20+
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
21+
22+
==== Path Parameters
23+
24+
`username` (required)::
25+
(string) An identifier for the user.
26+
27+
//==== Request Body
28+
29+
==== Authorization
30+
31+
To use this API, you must have at least the `manage_security` cluster privilege.
32+
33+
34+
==== Examples
35+
36+
The following example disables the user `jacknich`:
37+
38+
[source,js]
39+
--------------------------------------------------
40+
PUT /_xpack/security/user/jacknich/_disable
41+
--------------------------------------------------
42+
// CONSOLE
43+
// TEST[setup:jacknich_user]

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
[role="xpack"]
2+
[[security-api-enable-user]]
3+
=== Enable users API
4+
5+
Enables users in the native realm.
6+
7+
8+
==== Request
9+
10+
`PUT /_xpack/security/user/<username>/_enable`
11+
12+
13+
==== Description
14+
15+
By default, when you create users, they are enabled. You can use this enable
16+
users API and the <<security-api-disable-user,disable users API>> to change that attribute.
17+
18+
For more information about the native realm, see
19+
{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>.
20+
21+
==== Path Parameters
22+
23+
`username` (required)::
24+
(string) An identifier for the user.
25+
26+
//==== Request Body
27+
28+
==== Authorization
29+
30+
To use this API, you must have at least the `manage_security` cluster privilege.
31+
32+
33+
==== Examples
34+
35+
The following example enables the user `jacknich`:
36+
37+
[source,js]
38+
--------------------------------------------------
39+
PUT /_xpack/security/user/jacknich/_enable
40+
--------------------------------------------------
41+
// CONSOLE
42+
// TEST[setup:jacknich_user]

0 commit comments

Comments
 (0)