226 lines
6.0 KiB
Plaintext
226 lines
6.0 KiB
Plaintext
[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
|
|
--------------------------------------------------
|
|
|
|
[[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
|