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

docs/reference/redirects.asciidoc

@@ -515,3 +515,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

@@ -737,3 +737,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
-of a user.
+Changes the passwords of users in the native realm.
 
 ==== 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]