From bb2ac2f181f56d173aa3bc808b9daf5d181f0122 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 10 Aug 2018 17:08:24 -0700 Subject: [PATCH 1/7] [DOCS] Splits the users API documentation into multiple pages --- x-pack/docs/en/rest-api/security.asciidoc | 7 +- .../rest-api/security/create-users.asciidoc | 146 +++++++++++ .../rest-api/security/delete-users.asciidoc | 45 ++++ .../en/rest-api/security/get-users.asciidoc | 77 ++++++ .../docs/en/rest-api/security/users.asciidoc | 229 +----------------- 5 files changed, 279 insertions(+), 225 deletions(-) create mode 100644 x-pack/docs/en/rest-api/security/create-users.asciidoc create mode 100644 x-pack/docs/en/rest-api/security/delete-users.asciidoc create mode 100644 x-pack/docs/en/rest-api/security/get-users.asciidoc diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 27e54df38b31c..63cee47acc276 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -9,7 +9,6 @@ You can use the following APIs to perform {security} activities. * <> * <> * <> -* <> [float] [[security-role-apis]] @@ -30,16 +29,20 @@ without requiring basic authentication: * <>, <> +include::security/users.asciidoc[] + 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/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[] diff --git a/x-pack/docs/en/rest-api/security/create-users.asciidoc b/x-pack/docs/en/rest-api/security/create-users.asciidoc new file mode 100644 index 0000000000000..0fe407724a762 --- /dev/null +++ b/x-pack/docs/en/rest-api/security/create-users.asciidoc @@ -0,0 +1,146 @@ +[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/` + + +`PUT /_xpack/security/user/` + + +`PUT /_xpack/security/user//_disable` + + +`PUT /_xpack/security/user//_enable` + + +`PUT /_xpack/security/user//_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 <>. + +[[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. + + +==== 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 + +To add a user, submit a PUT or POST request to the `/_xpack/security/user/` +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-reset-user-password]] +To reset the password for a user, submit a PUT request to the +`/_xpack/security/user//_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//_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//_enable` endpoint: + +[source,js] +-------------------------------------------------- +PUT /_xpack/security/user/jacknich/_enable +-------------------------------------------------- +// CONSOLE +// TEST[continued] diff --git a/x-pack/docs/en/rest-api/security/delete-users.asciidoc b/x-pack/docs/en/rest-api/security/delete-users.asciidoc new file mode 100644 index 0000000000000..8db973bfe5fe3 --- /dev/null +++ b/x-pack/docs/en/rest-api/security/delete-users.asciidoc @@ -0,0 +1,45 @@ +[role="xpack"] +[[security-api-delete-user]] +=== Delete users API + +Deletes users from the native realm. + +==== Request + +`DELETE /_xpack/security/user/` + +//==== Description + +==== Path Parameters + +`username`:: + (string) An identifier for the user. + +//==== Request Body + +==== Authorization + +To use this API, you must have at least the `manage_security` cluster privilege. + + +==== Examples + +To delete a user, submit a DELETE request to the `/_xpack/security/user/` +endpoint: + +[source,js] +-------------------------------------------------- +DELETE /_xpack/security/user/jacknich +-------------------------------------------------- +// CONSOLE + +If the user is successfully deleted, the request returns `{"found": true}`. +Otherwise, `found` is set to false. + +[source,js] +-------------------------------------------------- +{ + "found" : true +} +-------------------------------------------------- +// TESTRESPONSE diff --git a/x-pack/docs/en/rest-api/security/get-users.asciidoc b/x-pack/docs/en/rest-api/security/get-users.asciidoc new file mode 100644 index 0000000000000..48ba09506804d --- /dev/null +++ b/x-pack/docs/en/rest-api/security/get-users.asciidoc @@ -0,0 +1,77 @@ +[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/` + +//==== Description + +==== 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 + +==== 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/` +endpoint: + +[source,js] +-------------------------------------------------- +GET /_xpack/security/user/jacknich +-------------------------------------------------- +// CONSOLE + +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] diff --git a/x-pack/docs/en/rest-api/security/users.asciidoc b/x-pack/docs/en/rest-api/security/users.asciidoc index c84da5c7d75ff..67131dbfec25c 100644 --- a/x-pack/docs/en/rest-api/security/users.asciidoc +++ b/x-pack/docs/en/rest-api/security/users.asciidoc @@ -1,226 +1,9 @@ -[role="xpack"] +[float] [[security-api-users]] -=== User Management APIs +=== Users -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*. +You can use the following APIs to create, read, update, and delete users from the +native realm: - -==== Request - -`GET /_xpack/security/user` + - -`GET /_xpack/security/user/` + - -`DELETE /_xpack/security/user/` + - -`POST /_xpack/security/user/` + - -`PUT /_xpack/security/user/` + - -`PUT /_xpack/security/user//_disable` + - -`PUT /_xpack/security/user//_enable` + - -`PUT /_xpack/security/user//_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 <>. - -[[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/` -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/` -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//_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//_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//_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/` -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 +* <>, <> +* <> From 3c18b00ef3f01576b2c5ce85e5b4330ded94dddd Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 10 Aug 2018 17:10:22 -0700 Subject: [PATCH 2/7] [DOCS] Updates documentation URL in REST API specs --- .../resources/rest-api-spec/api/xpack.security.delete_user.json | 2 +- .../resources/rest-api-spec/api/xpack.security.get_user.json | 2 +- .../resources/rest-api-spec/api/xpack.security.put_user.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.delete_user.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.delete_user.json index d72c854a69dcb..fa1deb3e1ec13 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.delete_user.json +++ b/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}", diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.get_user.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.get_user.json index 910fb7d064582..94dcbca81e18e 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.get_user.json +++ b/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}", diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.put_user.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.put_user.json index de07498a40954..1b51783a05ef5 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.put_user.json +++ b/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}", From 2f893a137c341b908b8d8fd184440def3275c8fe Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 13 Aug 2018 15:01:21 -0700 Subject: [PATCH 3/7] [DOCS] Fixes examples for user APIs --- x-pack/docs/build.gradle | 15 ++++ x-pack/docs/en/rest-api/security.asciidoc | 2 + .../security/change-password.asciidoc | 21 +++-- .../rest-api/security/create-users.asciidoc | 77 +++++-------------- .../rest-api/security/delete-users.asciidoc | 9 ++- .../rest-api/security/disable-users.asciidoc | 46 +++++++++++ .../rest-api/security/enable-users.asciidoc | 44 +++++++++++ .../en/rest-api/security/get-users.asciidoc | 19 ++--- .../docs/en/rest-api/security/users.asciidoc | 2 + 9 files changed, 156 insertions(+), 79 deletions(-) create mode 100644 x-pack/docs/en/rest-api/security/disable-users.asciidoc create mode 100644 x-pack/docs/en/rest-api/security/enable-users.asciidoc diff --git a/x-pack/docs/build.gradle b/x-pack/docs/build.gradle index 48ac4ba565e55..942cb041e5329 100644 --- a/x-pack/docs/build.gradle +++ b/x-pack/docs/build.gradle @@ -736,3 +736,18 @@ setups['admin_role'] = ''' "metadata" : {"version": 1} } ''' +setups['jacknich_user'] = ''' + - do: + xpack.security.put_user: + username: "jacknich" + body: > + { + "password" : "j@rV1s", + "roles" : [ "admin", "other_role1" ], + "full_name" : "Jack Nicholson", + "email" : "jacknich@example.com", + "metadata" : { + "intelligence" : 7 + } + } +''' diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 63cee47acc276..2c4d807d21e0d 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -40,6 +40,8 @@ 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[] diff --git a/x-pack/docs/en/rest-api/security/change-password.asciidoc b/x-pack/docs/en/rest-api/security/change-password.asciidoc index 7dee98480e72c..6e6e8cf7375e4 100644 --- a/x-pack/docs/en/rest-api/security/change-password.asciidoc +++ b/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//_password` +==== Description + +You can use the <> 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 <>. + + ==== 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. diff --git a/x-pack/docs/en/rest-api/security/create-users.asciidoc b/x-pack/docs/en/rest-api/security/create-users.asciidoc index 0fe407724a762..82c57942af3b2 100644 --- a/x-pack/docs/en/rest-api/security/create-users.asciidoc +++ b/x-pack/docs/en/rest-api/security/create-users.asciidoc @@ -3,44 +3,42 @@ === Create users API Creates and updates users in the native realm. These users are commonly referred -to as *native users*. +to as _native users_. ==== Request `POST /_xpack/security/user/` + -`PUT /_xpack/security/user/` + +`PUT /_xpack/security/user/` -`PUT /_xpack/security/user//_disable` + -`PUT /_xpack/security/user//_enable` + - -`PUT /_xpack/security/user//_password` +==== Description +When updating a user, you can update everything but its `username` and `password`. +To change a user's password, use the +<>. -==== Description +For more information about the native realm, see +{stack-ov}/realms.html[Realms] and <>. -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 <>. +==== Path Parameters +`username`:: + (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. - -==== Path Parameters +printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block]. Leading or trailing whitespace is not allowed. -`username`:: - (string) An identifier for the user. +-- ==== Request Body -The following parameters can be specified in the body of a POST or PUT request -and pertain to creating a user: +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`. @@ -61,6 +59,7 @@ and pertain to creating a user: (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. @@ -68,8 +67,7 @@ To use this API, you must have at least the `manage_security` cluster privilege. ==== Examples -To add a user, submit a PUT or POST request to the `/_xpack/security/user/` -endpoint. +For example, to create a user `jacknich`: [source,js] -------------------------------------------------- @@ -100,47 +98,10 @@ created or updated. // 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: +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 - -[[security-api-reset-user-password]] -To reset the password for a user, submit a PUT request to the -`/_xpack/security/user//_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//_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//_enable` endpoint: - -[source,js] --------------------------------------------------- -PUT /_xpack/security/user/jacknich/_enable --------------------------------------------------- -// CONSOLE -// TEST[continued] diff --git a/x-pack/docs/en/rest-api/security/delete-users.asciidoc b/x-pack/docs/en/rest-api/security/delete-users.asciidoc index 8db973bfe5fe3..0da19c6b21c92 100644 --- a/x-pack/docs/en/rest-api/security/delete-users.asciidoc +++ b/x-pack/docs/en/rest-api/security/delete-users.asciidoc @@ -8,7 +8,10 @@ Deletes users from the native realm. `DELETE /_xpack/security/user/` -//==== Description +==== Description + +For more information about the native realm, see +{stack-ov}/realms.html[Realms] and <>. ==== Path Parameters @@ -24,14 +27,14 @@ To use this API, you must have at least the `manage_security` cluster privilege. ==== Examples -To delete a user, submit a DELETE request to the `/_xpack/security/user/` -endpoint: +For example, to delete a `jacknich` user: [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. diff --git a/x-pack/docs/en/rest-api/security/disable-users.asciidoc b/x-pack/docs/en/rest-api/security/disable-users.asciidoc new file mode 100644 index 0000000000000..02aabd69d75bc --- /dev/null +++ b/x-pack/docs/en/rest-api/security/disable-users.asciidoc @@ -0,0 +1,46 @@ +[role="xpack"] +[[security-api-disable-user]] +=== Disable users API + +Disables users in the native realm. + + +==== Request + +`PUT /_xpack/security/user//_disable` + + +==== Description + +By default, when you create users, they are enabled. +//TBD: What is disallowed when a user is disabled? Is it just intended for +// temporarily revoking access? +You can use this disable users API and the <> to change that attribute. + +For more information about the native realm, see +{stack-ov}/realms.html[Realms] and <>. + +==== Path Parameters + +`username`:: + (string) An identifier for the user. +//TBD: Can you specify multiple users in a comma-delimited list? If you don't +//specify a user, does it disable all users? + +//==== Request Body + +==== Authorization + +To use this API, you must have at least the `manage_security` cluster privilege. + + +==== Examples + +For example, to disable a user `jacknich`: + +[source,js] +-------------------------------------------------- +PUT /_xpack/security/user/jacknich/_disable +-------------------------------------------------- +// CONSOLE +// TEST[setup:jacknich_user] diff --git a/x-pack/docs/en/rest-api/security/enable-users.asciidoc b/x-pack/docs/en/rest-api/security/enable-users.asciidoc new file mode 100644 index 0000000000000..001f5fda6543a --- /dev/null +++ b/x-pack/docs/en/rest-api/security/enable-users.asciidoc @@ -0,0 +1,44 @@ +[role="xpack"] +[[security-api-enable-user]] +=== Enable users API + +Enables users in the native realm. + + +==== Request + +`PUT /_xpack/security/user//_enable` + + +==== Description + +By default, when you create users, they are enabled. You can use this enable +users API and the <> to change that attribute. + +For more information about the native realm, see +{stack-ov}/realms.html[Realms] and <>. + +==== Path Parameters + +`username`:: + (string) An identifier for the user. +//TBD: Can you specify multiple users in a comma-delimited list? If you don't +//specify a user, does it enable all users? + +//==== Request Body + +==== Authorization + +To use this API, you must have at least the `manage_security` cluster privilege. + + +==== Examples + +For example, to enable the user `jacknich`: + +[source,js] +-------------------------------------------------- +PUT /_xpack/security/user/jacknich/_enable +-------------------------------------------------- +// CONSOLE +// TEST[setup:jacknich_user] diff --git a/x-pack/docs/en/rest-api/security/get-users.asciidoc b/x-pack/docs/en/rest-api/security/get-users.asciidoc index 48ba09506804d..af1cc83971f8f 100644 --- a/x-pack/docs/en/rest-api/security/get-users.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-users.asciidoc @@ -11,13 +11,16 @@ Retrieves information about users in the native realm. `GET /_xpack/security/user/` -//==== Description +==== Description + +For more information about the native realm, see +{stack-ov}/realms.html[Realms] and <>. ==== 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. + (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 @@ -36,6 +39,7 @@ endpoint: 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. @@ -58,15 +62,6 @@ user. Note that user passwords are not included. // 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] diff --git a/x-pack/docs/en/rest-api/security/users.asciidoc b/x-pack/docs/en/rest-api/security/users.asciidoc index 67131dbfec25c..d378a17df2378 100644 --- a/x-pack/docs/en/rest-api/security/users.asciidoc +++ b/x-pack/docs/en/rest-api/security/users.asciidoc @@ -6,4 +6,6 @@ You can use the following APIs to create, read, update, and delete users from th native realm: * <>, <> +* <>, <> +* <> * <> From 9ce5c2543181ae958cbf5dfacd6a8b609cd0dadd Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 13 Aug 2018 15:42:33 -0700 Subject: [PATCH 4/7] [DOCS] Clarifies required parameters --- x-pack/docs/en/rest-api/security/create-users.asciidoc | 4 ++-- x-pack/docs/en/rest-api/security/delete-users.asciidoc | 4 ++-- x-pack/docs/en/rest-api/security/disable-users.asciidoc | 6 ++---- x-pack/docs/en/rest-api/security/enable-users.asciidoc | 6 ++---- 4 files changed, 8 insertions(+), 12 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/create-users.asciidoc b/x-pack/docs/en/rest-api/security/create-users.asciidoc index 82c57942af3b2..5015d0401c223 100644 --- a/x-pack/docs/en/rest-api/security/create-users.asciidoc +++ b/x-pack/docs/en/rest-api/security/create-users.asciidoc @@ -24,7 +24,7 @@ For more information about the native realm, see ==== Path Parameters -`username`:: +`username` (required):: (string) An identifier for the user. + -- @@ -67,7 +67,7 @@ To use this API, you must have at least the `manage_security` cluster privilege. ==== Examples -For example, to create a user `jacknich`: +The following example creates a user `jacknich`: [source,js] -------------------------------------------------- diff --git a/x-pack/docs/en/rest-api/security/delete-users.asciidoc b/x-pack/docs/en/rest-api/security/delete-users.asciidoc index 0da19c6b21c92..63a66795617bd 100644 --- a/x-pack/docs/en/rest-api/security/delete-users.asciidoc +++ b/x-pack/docs/en/rest-api/security/delete-users.asciidoc @@ -15,7 +15,7 @@ For more information about the native realm, see ==== Path Parameters -`username`:: +`username` (required):: (string) An identifier for the user. //==== Request Body @@ -27,7 +27,7 @@ To use this API, you must have at least the `manage_security` cluster privilege. ==== Examples -For example, to delete a `jacknich` user: +The following example deletes the user `jacknich`: [source,js] -------------------------------------------------- diff --git a/x-pack/docs/en/rest-api/security/disable-users.asciidoc b/x-pack/docs/en/rest-api/security/disable-users.asciidoc index 02aabd69d75bc..e9b36ae07a262 100644 --- a/x-pack/docs/en/rest-api/security/disable-users.asciidoc +++ b/x-pack/docs/en/rest-api/security/disable-users.asciidoc @@ -22,10 +22,8 @@ For more information about the native realm, see ==== Path Parameters -`username`:: +`username` (required):: (string) An identifier for the user. -//TBD: Can you specify multiple users in a comma-delimited list? If you don't -//specify a user, does it disable all users? //==== Request Body @@ -36,7 +34,7 @@ To use this API, you must have at least the `manage_security` cluster privilege. ==== Examples -For example, to disable a user `jacknich`: +The following example disables the user `jacknich`: [source,js] -------------------------------------------------- diff --git a/x-pack/docs/en/rest-api/security/enable-users.asciidoc b/x-pack/docs/en/rest-api/security/enable-users.asciidoc index 001f5fda6543a..cebaaffa7b28d 100644 --- a/x-pack/docs/en/rest-api/security/enable-users.asciidoc +++ b/x-pack/docs/en/rest-api/security/enable-users.asciidoc @@ -20,10 +20,8 @@ For more information about the native realm, see ==== Path Parameters -`username`:: +`username` (required):: (string) An identifier for the user. -//TBD: Can you specify multiple users in a comma-delimited list? If you don't -//specify a user, does it enable all users? //==== Request Body @@ -34,7 +32,7 @@ To use this API, you must have at least the `manage_security` cluster privilege. ==== Examples -For example, to enable the user `jacknich`: +The following example enables the user `jacknich`: [source,js] -------------------------------------------------- From 32f0b815eb647647fff5ddcc65c1d9401d99e453 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 17 Aug 2018 09:15:50 -0700 Subject: [PATCH 5/7] [DOCS] Updates URLs in disable and enable user specs --- x-pack/docs/en/rest-api/security/disable-users.asciidoc | 7 +++---- .../rest-api-spec/api/xpack.security.disable_user.json | 2 +- .../rest-api-spec/api/xpack.security.enable_user.json | 2 +- 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/disable-users.asciidoc b/x-pack/docs/en/rest-api/security/disable-users.asciidoc index e9b36ae07a262..f5a6bc7e9a136 100644 --- a/x-pack/docs/en/rest-api/security/disable-users.asciidoc +++ b/x-pack/docs/en/rest-api/security/disable-users.asciidoc @@ -12,10 +12,9 @@ Disables users in the native realm. ==== Description -By default, when you create users, they are enabled. -//TBD: What is disallowed when a user is disabled? Is it just intended for -// temporarily revoking access? -You can use this disable users API and the <> to change that attribute. +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 +<>. For more information about the native realm, see {stack-ov}/realms.html[Realms] and <>. diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.disable_user.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.disable_user.json index 3a72b3141911f..0e55e82ead628 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.disable_user.json +++ b/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", diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.enable_user.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.enable_user.json index c68144957f07d..da2f67adbea37 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.enable_user.json +++ b/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", From 1bb7d75456fc77768c9a46902abf756a8e5d0d7f Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 17 Aug 2018 15:58:27 -0700 Subject: [PATCH 6/7] [DOCS] Fixes gradle errors --- x-pack/docs/build.gradle | 20 +++++++--------- .../en/rest-api/security/get-users.asciidoc | 24 ++++++++++--------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/x-pack/docs/build.gradle b/x-pack/docs/build.gradle index 942cb041e5329..aab8435558198 100644 --- a/x-pack/docs/build.gradle +++ b/x-pack/docs/build.gradle @@ -739,15 +739,13 @@ setups['admin_role'] = ''' setups['jacknich_user'] = ''' - do: xpack.security.put_user: - username: "jacknich" - body: > - { - "password" : "j@rV1s", - "roles" : [ "admin", "other_role1" ], - "full_name" : "Jack Nicholson", - "email" : "jacknich@example.com", - "metadata" : { - "intelligence" : 7 - } - } + username: "jacknich" + body: > + { + "password" : "test-password", + "roles" : [ "admin", "other_role1" ], + "full_name" : "Jack Nicholson", + "email" : "jacknich@example.com", + "metadata" : { "intelligence" : 7 } + } ''' diff --git a/x-pack/docs/en/rest-api/security/get-users.asciidoc b/x-pack/docs/en/rest-api/security/get-users.asciidoc index af1cc83971f8f..2a20baacb0f52 100644 --- a/x-pack/docs/en/rest-api/security/get-users.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-users.asciidoc @@ -46,21 +46,23 @@ 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 - } +{ + "jacknich": { + "username": "jacknich", + "roles": [ + "admin", "other_role1" + ], + "full_name": "Jack Nicholson", + "email": "jacknich@example.com", + "metadata": { "intelligence" : 7 }, + "enabled": true } } -------------------------------------------------- +// CONSOLE // TESTRESPONSE -<1> If the user is not defined in the `native` realm, the request 404s. + +If the user is not defined in the `native` realm, the request 404s. Omit the username to retrieve all users: From aa226545161870bf3299c96542aeb2610f29fad6 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 17 Aug 2018 16:56:20 -0700 Subject: [PATCH 7/7] [DOCS] Adds redirects for user management APIs --- docs/reference/redirects.asciidoc | 11 +++++++++++ x-pack/docs/en/rest-api/security.asciidoc | 12 +++++++++++- x-pack/docs/en/rest-api/security/users.asciidoc | 11 ----------- 3 files changed, 22 insertions(+), 12 deletions(-) delete mode 100644 x-pack/docs/en/rest-api/security/users.asciidoc diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 948652c37e69a..d67d8a733ac00 100644 --- a/docs/reference/redirects.asciidoc +++ b/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: * <>, <> + +[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: + +* <>, <> +* <>, <> +* <> +* <> diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 2c4d807d21e0d..f5b0c8eef667d 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -29,7 +29,17 @@ without requiring basic authentication: * <>, <> -include::security/users.asciidoc[] +[float] +[[security-user-apis]] +=== Users + +You can use the following APIs to create, read, update, and delete users from the +native realm: + +* <>, <> +* <>, <> +* <> +* <> include::security/authenticate.asciidoc[] include::security/change-password.asciidoc[] diff --git a/x-pack/docs/en/rest-api/security/users.asciidoc b/x-pack/docs/en/rest-api/security/users.asciidoc deleted file mode 100644 index d378a17df2378..0000000000000 --- a/x-pack/docs/en/rest-api/security/users.asciidoc +++ /dev/null @@ -1,11 +0,0 @@ -[float] -[[security-api-users]] -=== Users - -You can use the following APIs to create, read, update, and delete users from the -native realm: - -* <>, <> -* <>, <> -* <> -* <>