[DOCS] Splits the users API documentation into multiple pages (#32825)

docs/reference/redirects.asciidoc

@@ -520,3 +520,14 @@ You can use the following APIs to create and invalidate bearer tokens for access
 without requiring basic authentication:
 
 * <<security-api-get-token,Get token>>, <<security-api-invalidate-token,Invalidate token>>
+
+[role="exclude",id="security-api-users"]
+=== User Management APIs
+
+You can use the following APIs to create, read, update, and delete users from the
+native realm:
+
+* <<security-api-put-user,Create users>>, <<security-api-delete-user,Delete users>>
+* <<security-api-enable-user,Enable users>>, <<security-api-disable-user,Disable users>>
+* <<security-api-change-password,Change passwords>>
+* <<security-api-get-user,Get users>>

x-pack/docs/build.gradle

@@ -736,3 +736,16 @@ setups['admin_role'] = '''
             "metadata" : {"version": 1}
           }
 '''
+setups['jacknich_user'] = '''
+  - do:
+      xpack.security.put_user:
+        username: "jacknich"
+        body:  >
+          {
+            "password" : "test-password",
+            "roles" : [ "admin", "other_role1" ],
+            "full_name" : "Jack Nicholson",
+            "email" : "jacknich@example.com",
+            "metadata" : { "intelligence" : 7 }
+          }
+'''

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

@@ -9,7 +9,6 @@ You can use the following APIs to perform {security} activities.
 * <<security-api-privileges>>
 * <<security-api-role-mapping>>
 * <<security-api-ssl>>
-* <<security-api-users>>
 
 [float]
 [[security-role-apis]]
@@ -30,16 +29,32 @@ without requiring basic authentication:
 
 * <<security-api-get-token,Get token>>, <<security-api-invalidate-token,Invalidate token>>
 
+[float]
+[[security-user-apis]]
+=== Users
+
+You can use the following APIs to create, read, update, and delete users from the
+native realm:
+
+* <<security-api-put-user,Create users>>, <<security-api-delete-user,Delete users>>
+* <<security-api-enable-user,Enable users>>, <<security-api-disable-user,Disable users>>
+* <<security-api-change-password,Change passwords>>
+* <<security-api-get-user,Get users>>
+
 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/create-users.asciidoc[]
 include::security/delete-roles.asciidoc[]
 include::security/delete-tokens.asciidoc[]
+include::security/delete-users.asciidoc[]
+include::security/disable-users.asciidoc[]
+include::security/enable-users.asciidoc[]
 include::security/get-roles.asciidoc[]
 include::security/get-tokens.asciidoc[]
+include::security/get-users.asciidoc[]
 include::security/privileges.asciidoc[]
 include::security/role-mapping.asciidoc[]
 include::security/ssl.asciidoc[]
-include::security/users.asciidoc[]

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

@@ -1,9 +1,8 @@
 [role="xpack"]
 [[security-api-change-password]]
-=== Change Password API
+=== Change passwords API
 
-The Change Password API enables you to submit a request to change the password
+Changes the passwords of users in the native realm.
-of a user.
 
 ==== Request
 
@@ -12,6 +11,15 @@ of a user.
 `POST _xpack/security/user/<username>/_password`
 
 
+==== Description
+
+You can use the <<security-api-put-user,create user API>> to update everything 
+but a user's `username` and `password`. This API changes a user's password.
+
+For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+
+
 ==== Path Parameters
 
 `username`::
@@ -33,16 +41,17 @@ privilege can change passwords of other users.
 
 ==== Examples
 
-The following example updates the password for the `elastic` user:
+The following example updates the password for the `jacknich` user:
 
 [source,js]
 --------------------------------------------------
-POST _xpack/security/user/elastic/_password
+POST /_xpack/security/user/jacknich/_password
 {
-  "password": "x-pack-test-password"
+  "password" : "s3cr3t"
 }
 --------------------------------------------------
 // CONSOLE
+// TEST[setup:jacknich_user]
 
 A successful call returns an empty JSON structure.
 

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

@@ -0,0 +1,107 @@
+[role="xpack"]
+[[security-api-put-user]]
+=== Create users API
+
+Creates and updates users in the native realm. These users are commonly referred 
+to as _native users_.
+
+
+==== Request
+
+`POST /_xpack/security/user/<username>` +
+
+`PUT /_xpack/security/user/<username>` 
+
+
+==== Description
+
+When updating a user, you can update everything but its `username` and `password`. 
+To change a user's password, use the 
+<<security-api-change-password, change password API>>.
+
+For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+
+==== Path Parameters
+
+`username` (required)::
+  (string) An identifier for the user.
++
+--
+[[username-validation]]
+NOTE: Usernames must be at least 1 and no more than 1024 characters. They can
+contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and
+printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block]. Leading or trailing whitespace is not allowed.
+
+--
+
+
+==== Request Body
+
+The following parameters can be specified in the body of a POST or PUT request:
+
+`enabled`::
+(boolean) Specifies whether the user is enabled. The default value is `true`.
+
+`email`::
+(string) The email of the user.
+
+`full_name`::
+(string) The full name of the user.
+
+`metadata`::
+(object) Arbitrary metadata that you want to associate with the user.
+
+`password` (required)::
+(string) The user's password. Passwords must be at least 6 characters long. 
+
+`roles` (required)::
+(list) A set of roles the user has. The roles determine the user's access 
+permissions. To create a user without any roles, specify an empty list: `[]`.
+
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+==== Examples
+
+The following example creates a user `jacknich`:
+
+[source,js]
+--------------------------------------------------
+POST /_xpack/security/user/jacknich
+{
+  "password" : "j@rV1s",
+  "roles" : [ "admin", "other_role1" ],
+  "full_name" : "Jack Nicholson",
+  "email" : "jacknich@example.com",
+  "metadata" : {
+    "intelligence" : 7
+  }
+}
+--------------------------------------------------
+// CONSOLE
+
+A successful call returns a JSON structure that shows whether the user has been
+created or updated.
+
+[source,js]
+--------------------------------------------------
+{
+  "user": {
+    "created" : true <1>
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE
+<1> When an existing user is updated, `created` is set to false.
+
+After you add a user, requests from that user can be authenticated. For example:
+
+[source,shell]
+--------------------------------------------------
+curl -u jacknich:j@rV1s http://localhost:9200/_cluster/health
+--------------------------------------------------
+// NOTCONSOLE

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

@@ -0,0 +1,48 @@
+[role="xpack"]
+[[security-api-delete-user]]
+=== Delete users API
+
+Deletes users from the native realm. 
+
+==== Request
+
+`DELETE /_xpack/security/user/<username>` 
+
+==== Description
+
+For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+
+==== Path Parameters
+
+`username` (required)::
+  (string) An identifier for the user. 
+
+//==== Request Body
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+==== Examples
+
+The following example deletes the user `jacknich`:
+
+[source,js]
+--------------------------------------------------
+DELETE /_xpack/security/user/jacknich
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:jacknich_user]
+
+If the user 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/disable-users.asciidoc

@@ -0,0 +1,43 @@
+[role="xpack"]
+[[security-api-disable-user]]
+=== Disable users API
+
+Disables users in the native realm. 
+
+
+==== Request
+
+`PUT /_xpack/security/user/<username>/_disable` 
+
+
+==== Description
+
+By default, when you create users, they are enabled. You can use this API to 
+revoke a user's access to {es}. To re-enable a user, there is an 
+<<security-api-enable-user,enable users API>>. 
+
+For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+
+==== Path Parameters
+
+`username` (required)::
+  (string) An identifier for the user.
+
+//==== Request Body
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+==== Examples
+
+The following example disables the user `jacknich`:
+
+[source,js]
+--------------------------------------------------
+PUT /_xpack/security/user/jacknich/_disable
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:jacknich_user]

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

@@ -0,0 +1,42 @@
+[role="xpack"]
+[[security-api-enable-user]]
+=== Enable users API
+
+Enables users in the native realm. 
+
+
+==== Request
+
+`PUT /_xpack/security/user/<username>/_enable` 
+
+
+==== Description
+
+By default, when you create users, they are enabled. You can use this enable 
+users API and the <<security-api-disable-user,disable users API>> to change that attribute. 
+
+For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+
+==== Path Parameters
+
+`username` (required)::
+  (string) An identifier for the user.
+
+//==== Request Body
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+==== Examples
+
+The following example enables the user `jacknich`:
+
+[source,js]
+--------------------------------------------------
+PUT /_xpack/security/user/jacknich/_enable
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:jacknich_user]

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

@@ -0,0 +1,74 @@
+[role="xpack"]
+[[security-api-get-user]]
+=== Get users API
+
+Retrieves information about users in the native realm. 
+
+
+==== Request
+
+`GET /_xpack/security/user` +
+
+`GET /_xpack/security/user/<username>` 
+
+==== Description
+
+For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
+
+==== Path Parameters
+
+`username`::
+  (string) An identifier for the user. You can specify multiple usernames as a comma-separated list. If you omit this parameter, the API retrieves 
+  information about all users.
+
+//==== Request Body
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+==== Examples
+
+To retrieve a native user, submit a GET request to the `/_xpack/security/user/<username>`
+endpoint:
+
+[source,js]
+--------------------------------------------------
+GET /_xpack/security/user/jacknich
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:jacknich_user]
+
+A successful call returns an array of users with the JSON representation of the
+user. Note that user passwords are not included.
+
+[source,js]
+--------------------------------------------------
+{  
+  "jacknich": {
+    "username": "jacknich",
+    "roles": [
+      "admin", "other_role1"
+    ],
+    "full_name": "Jack Nicholson",
+    "email": "jacknich@example.com",
+    "metadata": { "intelligence" : 7 },
+    "enabled": true
+  }
+}
+--------------------------------------------------
+// CONSOLE
+// TESTRESPONSE
+
+If the user is not defined in the `native` realm, the request 404s.
+
+Omit the username to retrieve all users:
+
+[source,js]
+--------------------------------------------------
+GET /_xpack/security/user
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]

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

@@ -1,226 +0,0 @@
-[role="xpack"]
-[[security-api-users]]
-=== User Management APIs
-
-The `user` API enables you to create, read, update, and delete users from the
-`native` realm. These users are commonly referred to as *native users*.
-
-
-==== Request
-
-`GET /_xpack/security/user` +
-
-`GET /_xpack/security/user/<username>` +
-
-`DELETE /_xpack/security/user/<username>` +
-
-`POST /_xpack/security/user/<username>` +
-
-`PUT /_xpack/security/user/<username>` +
-
-`PUT /_xpack/security/user/<username>/_disable` +
-
-`PUT /_xpack/security/user/<username>/_enable` +
-
-`PUT /_xpack/security/user/<username>/_password`
-
-
-==== Description
-
-You can use the PUT user API to create or update users. When updating a user,
-you can update everything but its `username` and `password`. To change a user's
-password, use the  <<security-api-reset-user-password, reset password API>>.
-
-[[username-validation]]
-NOTE: Usernames must be at least 1 and no more than 1024 characters. They can
-contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and
-printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block].
-Leading or trailing whitespace is not allowed.
-
-==== Path Parameters
-
-`username`::
-  (string) An identifier for the user. If you omit this parameter from a Get
-  User API request, it retrieves information about all users.
-
-
-==== Request Body
-
-The following parameters can be specified in the body of a POST or PUT request
-and pertain to creating a user:
-
-`enabled`::
-(boolean) Specifies whether the user is enabled. The default value is `true`.
-
-`email`::
-(string) The email of the user.
-
-`full_name`::
-(string) The full name of the user.
-
-`metadata`::
-(object) Arbitrary metadata that you want to associate with the user.
-
-`password` (required)::
-(string) The user's password. Passwords must be at least 6 characters long. 
-
-`roles` (required)::
-(list) A set of roles the user has. The roles determine the user's access 
-permissions. To create a user without any roles, specify an empty list: `[]`.
-
-==== Authorization
-
-To use this API, you must have at least the `manage_security` cluster privilege.
-
-
-==== Examples
-
-[[security-api-put-user]]
-To add a user, submit a PUT or POST request to the `/_xpack/security/user/<username>`
-endpoint.
-
-[source,js]
---------------------------------------------------
-POST /_xpack/security/user/jacknich
-{
-  "password" : "j@rV1s",
-  "roles" : [ "admin", "other_role1" ],
-  "full_name" : "Jack Nicholson",
-  "email" : "jacknich@example.com",
-  "metadata" : {
-    "intelligence" : 7
-  }
-}
---------------------------------------------------
-// CONSOLE
-
-A successful call returns a JSON structure that shows whether the user has been
-created or updated.
-
-[source,js]
---------------------------------------------------
-{
-  "user": {
-    "created" : true <1>
-  }
-}
---------------------------------------------------
-// TESTRESPONSE
-<1> When an existing user is updated, `created` is set to false.
-
-After you add a user through the Users API, requests from that user can be
-authenticated. For example:
-
-[source,shell]
---------------------------------------------------
-curl -u jacknich:j@rV1s http://localhost:9200/_cluster/health
---------------------------------------------------
-// NOTCONSOLE
-
-[[security-api-get-user]]
-To retrieve a native user, submit a GET request to the `/_xpack/security/user/<username>`
-endpoint:
-
-[source,js]
---------------------------------------------------
-GET /_xpack/security/user/jacknich
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-A successful call returns an array of users with the JSON representation of the
-user. Note that user passwords are not included.
-
-[source,js]
---------------------------------------------------
-{
-  "jacknich": {  <1>
-    "username" : "jacknich",
-    "roles" : [ "admin", "other_role1" ],
-    "full_name" : "Jack Nicholson",
-    "email" : "jacknich@example.com",
-    "enabled": true,
-    "metadata" : {
-      "intelligence" : 7
-    }
-  }
-}
---------------------------------------------------
-// TESTRESPONSE
-<1> If the user is not defined in the `native` realm, the request 404s.
-
-You can specify multiple usernames as a comma-separated list:
-
-[source,js]
---------------------------------------------------
-GET /_xpack/security/user/jacknich,rdinero
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-Omit the username to retrieve all users:
-
-[source,js]
---------------------------------------------------
-GET /_xpack/security/user
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-[[security-api-reset-user-password]]
-To reset the password for a user, submit a PUT request to the
-`/_xpack/security/user/<username>/_password` endpoint:
-
-[source,js]
---------------------------------------------------
-PUT /_xpack/security/user/jacknich/_password
-{
-  "password" : "s3cr3t"
-}
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-[[security-api-disable-user]]
-To disable a user, submit a PUT request to the
-`/_xpack/security/user/<username>/_disable` endpoint:
-
-[source,js]
---------------------------------------------------
-PUT /_xpack/security/user/jacknich/_disable
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-[[security-api-enable-user]]
-To enable a user, submit a PUT request to the
-`/_xpack/security/user/<username>/_enable` endpoint:
-
-[source,js]
---------------------------------------------------
-PUT /_xpack/security/user/jacknich/_enable
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-[[security-api-delete-user]]
-To delete a user, submit a DELETE request to the `/_xpack/security/user/<username>`
-endpoint:
-
-[source,js]
---------------------------------------------------
-DELETE /_xpack/security/user/jacknich
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-If the user is successfully deleted, the request returns `{"found": true}`.
-Otherwise, `found` is set to false.
-
-[source,js]
---------------------------------------------------
-{
-  "found" : true
-}
---------------------------------------------------
-// TESTRESPONSE

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.delete_user.json

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

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.disable_user.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.disable_user": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html#security-api-disable-user",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-disable-user.html",
     "methods": [ "PUT", "POST" ],
     "url": {
       "path": "/_xpack/security/user/{username}/_disable",

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.enable_user.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.enable_user": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-users.html#security-api-enable-user",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-enable-user.html",
     "methods": [ "PUT", "POST" ],
     "url": {
       "path": "/_xpack/security/user/{username}/_enable",

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.get_user.json

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

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.put_user.json

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