108 lines
2.7 KiB
Plaintext
108 lines
2.7 KiB
Plaintext
[role="xpack"]
|
|
[[security-api-put-user]]
|
|
=== Create or update users API
|
|
|
|
Adds 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
|