mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 15:47:23 -04:00
ea52277a1e
This commit adds a security client to the high level rest client, which includes an implementation for the put user api. As part of these changes, a new request and response class have been added that are specific to the high level rest client. One change here is that the response was previously wrapped inside a user object. The plan is to remove this wrapping and this PR adds an unwrapped response outside of the user object so we can remove the user object later on. See #29827
108 lines
2.8 KiB
Text
108 lines
2.8 KiB
Text
[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
|
|
},
|
|
"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
|