144 lines
4.1 KiB
Plaintext
144 lines
4.1 KiB
Plaintext
[role="xpack"]
|
|
[[security-api-put-user]]
|
|
=== Create or update users API
|
|
++++
|
|
<titleabbrev>Create or update users</titleabbrev>
|
|
++++
|
|
|
|
Adds and updates users in the native realm. These users are commonly referred
|
|
to as _native users_.
|
|
|
|
|
|
[[security-api-put-user-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_security/user/<username>` +
|
|
|
|
`PUT /_security/user/<username>`
|
|
|
|
|
|
[[security-api-put-user-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* To use this API, you must have at least the `manage_security` cluster privilege.
|
|
|
|
|
|
[[security-api-put-user-desc]]
|
|
==== {api-description-title}
|
|
|
|
A `password` is required for adding a new user but is optional when updating an
|
|
existing user. To change a user's password without updating any other fields,
|
|
use the <<security-api-change-password, change password API>>.
|
|
|
|
For more information about the native realm, see
|
|
<<realms>> and <<native-realm>>.
|
|
|
|
[[security-api-put-user-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`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 {wikipedia}/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block]. Leading or trailing whitespace is not allowed.
|
|
|
|
--
|
|
|
|
[[security-api-put-user-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`refresh`::
|
|
(string) One of `true`, `false`, or `wait_for`.
|
|
These values have the same meaning as in the <<docs-refresh, Index API>>,
|
|
but the default value for this API (Put User) is `true`.
|
|
|
|
[[security-api-put-user-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
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<<not-always-required,*>>, string) The user's password. Passwords must be at least 6 characters long.
|
|
+
|
|
When adding a user, one of `password` or `password_hash` is required.
|
|
When updating an existing user, the password is optional, so that other
|
|
fields on the user (such as their roles) may be updated without modifying
|
|
the user's password.
|
|
|
|
`password_hash`::
|
|
(string) A _hash_ of the user's password. This must be produced using the
|
|
same hashing algorithm as has been configured for password storage. For more
|
|
details, see the explanation of the
|
|
`xpack.security.authc.password_hashing.algorithm` setting in
|
|
<<hashing-settings>>.
|
|
+
|
|
Using this parameter allows the client to pre-hash the password for
|
|
performance and/or confidentiality reasons.
|
|
+
|
|
The `password` parameter and the `password_hash` parameter cannot be
|
|
used in the same request.
|
|
|
|
`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:
|
|
`[]`.
|
|
|
|
--
|
|
[[not-always-required]]
|
|
*Indicates that the setting is required in some, but not all situations.
|
|
--
|
|
|
|
[[security-api-put-user-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following example creates a user `jacknich`:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_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.
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"created": true <1>
|
|
}
|
|
--------------------------------------------------
|
|
|
|
<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
|