honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

This commit is contained in:
Lisa Cawley 2018-08-17 23:17:33 -07:00 committed by GitHub
parent fb1c3990d7
commit 532d552ffd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 375 additions and 239 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/reference/redirects.asciidoc
View File

@ -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>>

13
x-pack/docs/build.gradle
View File

@ -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 }
}
'''

19
x-pack/docs/en/rest-api/security.asciidoc
View File

@ -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[]

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

@ -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.

107
x-pack/docs/en/rest-api/security/create-users.asciidoc Normal file
View File

@ -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

48
x-pack/docs/en/rest-api/security/delete-users.asciidoc Normal file
View File

@ -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

43
x-pack/docs/en/rest-api/security/disable-users.asciidoc Normal file
View File

@ -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]

42
x-pack/docs/en/rest-api/security/enable-users.asciidoc Normal file
View File

@ -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]

74
x-pack/docs/en/rest-api/security/get-users.asciidoc Normal file
View File

@ -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]

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

@ -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

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

@ -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}",

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

@ -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",

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

@ -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",

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

@ -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}",

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

@ -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}",