From 4c38e610fdea773719d179f7342f50813c1bbb31 Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Tue, 17 Apr 2018 16:15:54 -0700
Subject: [PATCH] [DOCS] Adds enabled parameter to user management API
 (elastic/x-pack-elasticsearch#4364)

Original commit: elastic/x-pack-elasticsearch@166bef47029a33efa6bdd86b8af7a1b4d3fdd268
---
 docs/en/rest-api/security/users.asciidoc      |  15 ++-
 .../authentication/native-realm.asciidoc      | 111 +-----------------
 2 files changed, 14 insertions(+), 112 deletions(-)

diff --git a/docs/en/rest-api/security/users.asciidoc b/docs/en/rest-api/security/users.asciidoc
index 8aa2e1dc28e..926193481af 100644
--- a/docs/en/rest-api/security/users.asciidoc
+++ b/docs/en/rest-api/security/users.asciidoc
@@ -49,6 +49,9 @@ Leading or trailing whitespace is not allowed.
 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.
 
@@ -59,11 +62,11 @@ and pertain to creating a user:
 (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.
+(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.
+(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
 
@@ -106,11 +109,11 @@ created or updated.
 <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.
+authenticated. For example:
 
 [source,shell]
 --------------------------------------------------
-curl -u eustace:secret-password http://localhost:9200/_cluster/health
+curl -u jacknich:j@rV1s http://localhost:9200/_cluster/health
 --------------------------------------------------
 
 [[security-api-get-user]]
@@ -154,7 +157,7 @@ GET /_xpack/security/user/jacknich,rdinero
 // CONSOLE
 // TEST[continued]
 
-or omit the username all together to retrieve all users:
+Omit the username to retrieve all users:
 
 [source,js]
 --------------------------------------------------
diff --git a/docs/en/security/authentication/native-realm.asciidoc b/docs/en/security/authentication/native-realm.asciidoc
index f417d60e9e5..8cd150b9c1c 100644
--- a/docs/en/security/authentication/native-realm.asciidoc
+++ b/docs/en/security/authentication/native-realm.asciidoc
@@ -87,113 +87,12 @@ xpack:
 [[managing-native-users]]
 ==== Managing Native Users
 
-You manage users in the `native` realm through the
-{ref}/security-api-users.html[user API].
+{security} enables you to easily manage users in {kib} on the 
+*Management / Security / Users* page. 
+
+Alternatively, you can manage users through the `user` API. For more 
+information and examples, see {ref}/security-api-users.html[User Management APIs].
 
 [[migrating-from-file]]
 NOTE: To migrate file-based users to the `native` realm, use the
 {ref}/migrate-tool.html[migrate tool].
-
-[float]
-[[native-add]]
-===== Adding Users
-
-To add a user, submit a PUT or POST request to the `/_xpack/security/user/<username>`
-endpoint.
-
-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.
-
-[source,js]
---------------------------------------------------
-POST /_xpack/security/user/jacknich
-{
-  "password" : "j@rV1s", <1>
-  "roles" : [ "admin", "other_role1" ], <2>
-  "full_name" : "Jack Nicholson", <3>
-  "email" : "jacknich@example.com", <4>
-  "metadata" : { <5>
-    "intelligence" : 7
-  },
-  "enabled": true <6>
-}
---------------------------------------------------
-// CONSOLE
-<1> You must specify a password when adding a user. Passwords must be at least 6
-    characters long.
-<2> You must assign at least one role to the user. The roles determine the user's
-    access permissions.
-<3> The user's full name. Optional.
-<4> The user's email address. Optional.
-<5> Arbitrary metadata you want to associate with the user. Optional.
-<6> Specifies whether the user should be enabled. Optional with a default of true.
-
-
-[float]
-[[native-list]]
-===== Retrieving Users
-
-To retrieve all users, submit a GET request to the `/_xpack/security/user` endpoint:
-
-[source,js]
---------------------------------------------------
-GET /_xpack/security/user
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-To retrieve particular users, specify the users as a comma-separated list:
-
-[source,js]
---------------------------------------------------
-GET /_xpack/security/user/jacknich,rdeniro
---------------------------------------------------
-// CONSOLE
-// TEST[continued]
-
-An object is returned holding the found users, each keyed by the relevant
-username. Note that user passwords are not included.
-
-[source,js]
---------------------------------------------------
-{
-  "jacknich" : {
-    "username": "jacknich",
-    "roles" : [ "admin", "other_role1" ],
-    "full_name" : "Jack Nicholson",
-    "email" : "jacknich@example.com",
-    "enabled" : true,
-    "metadata" : {
-      "intelligence" : 7
-    }
-  }
-}
---------------------------------------------------
-// TESTRESPONSE
-
-[float]
-[[native-delete]]
-===== Deleting Users
-
-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