From dea7b6972e6967888057d422440b71b27717db68 Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Mon, 5 Nov 2018 13:04:52 +1100 Subject: [PATCH] DOCS: Add password_hash & refresh to Put User API PR #35242 formalised support for the password_hash field in the body of the Put User security API. Since this field is now validated and tested, it can also be documented. The Put User API also supports a "refresh" query parameter that was not documented. This commit adds it to the docs. --- .../rest-api/security/create-users.asciidoc | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/create-users.asciidoc b/x-pack/docs/en/rest-api/security/create-users.asciidoc index d18618af27345..f5a7f429277b2 100644 --- a/x-pack/docs/en/rest-api/security/create-users.asciidoc +++ b/x-pack/docs/en/rest-api/security/create-users.asciidoc @@ -35,6 +35,12 @@ printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_bloc -- +==== Query Parameters + +`refresh`:: + (string) One of `true`, `false`, or `wait_for`. + These values have the same meaning as in the <>, + but the default value for this API (Put User) is `true`. ==== Request Body @@ -52,8 +58,26 @@ The following parameters can be specified in the body of a POST or PUT request: `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. +`password` :: +(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 +<>. ++ +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