WARNING: Version 6.0 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
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.
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
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 reset password API.
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 Basic Latin (ASCII) block.
Leading or trailing whitespace is not allowed.
-
username
- (string) An identifier for the user. If you omit this parameter from a Get User API request, it retrieves information about all users.
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:
[]
.
To add a user, submit a PUT or POST request to the /_xpack/security/user/<username>
endpoint.
POST /_xpack/security/user/jacknich { "password" : "j@rV1s", "roles" : [ "admin", "other_role1" ], "full_name" : "Jack Nicholson", "email" : "jacknich@example.com", "metadata" : { "intelligence" : 7 } }
A successful call returns a JSON structure that shows whether the user has been created or updated.
After you add a user through the Users API, requests from that user can be authenticated. For example:
curl -u jacknich:j@rV1s http://localhost:9200/_cluster/health
To retrieve a native user, submit a GET request to the /_xpack/security/user/<username>
endpoint:
GET /_xpack/security/user/jacknich
A successful call returns an array of users with the JSON representation of the user. Note that user passwords are not included.
{ "jacknich": { "username" : "jacknich", "roles" : [ "admin", "other_role1" ], "full_name" : "Jack Nicholson", "email" : "jacknich@example.com", "enabled": true, "metadata" : { "intelligence" : 7 } } }
You can specify multiple usernames as a comma-separated list:
GET /_xpack/security/user/jacknich,rdinero
Omit the username to retrieve all users:
GET /_xpack/security/user
To reset the password for a user, submit a PUT request to the
/_xpack/security/user/<username>/_password
endpoint:
PUT /_xpack/security/user/jacknich/_password { "password" : "s3cr3t" }
To disable a user, submit a PUT request to the
/_xpack/security/user/<username>/_disable
endpoint:
PUT /_xpack/security/user/jacknich/_disable
To enable a user, submit a PUT request to the
/_xpack/security/user/<username>/_enable
endpoint:
PUT /_xpack/security/user/jacknich/_enable
To delete a user, submit a DELETE request to the /_xpack/security/user/<username>
endpoint:
DELETE /_xpack/security/user/jacknich
If the user is successfully deleted, the request returns {"found": true}
.
Otherwise, found
is set to false.
{ "found" : true }