mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-24 23:27:25 -04:00
c0b24df307
We were depending on the BouncyCastle FIPS own mechanics to set
itself in approved only mode since we run with the Security
Manager enabled. The check during startup seems to happen before we
set our restrictive SecurityManager though in
org.elasticsearch.bootstrap.Elasticsearch , and this means that
BCFIPS would not be in approved only mode, unless explicitly
configured so.
This commit sets the appropriate JVM property to explicitly set
BCFIPS in approved only mode in CI and adds tests to ensure that we
will be running with BCFIPS in approved only mode when we expect to.
It also sets xpack.security.fips_mode.enabled to true for all test clusters
used in fips mode and sets the distribution to the default one. It adds a
password to the elasticsearch keystore for all test clusters that run in fips
mode.
Moreover, it changes a few unit tests where we would use bcrypt even in
FIPS 140 mode. These would still pass since we are bundling our own
bcrypt implementation, but are now changed to use FIPS 140 approved
algorithms instead for better coverage.
It also addresses a number of tests that would fail in approved only mode
Mainly:
Tests that use PBKDF2 with a password less than 112 bits (14char). We
elected to change the passwords used everywhere to be at least 14
characters long instead of mandating
the use of pbkdf2_stretch because both pbkdf2 and
pbkdf2_stretch are supported and allowed in fips mode and it makes sense
to test with both. We could possibly figure out the password algorithm used
for each test and adjust password length accordingly only for pbkdf2 but
there is little value in that. It's good practice to use strong passwords so if
our docs and tests use longer passwords, then it's for the best. The approach
is brittle as there is no guarantee that the next test that will be added won't
use a short password, so we add some testing documentation too.
This leaves us with a possible coverage gap since we do support passwords
as short as 6 characters but we only test with > 14 chars but the
validation itself was not tested even before. Tests can be added in a followup,
outside of fips related context.
Tests that use a PKCS12 keystore and were not already muted.
Tests that depend on running test clusters with a basic license or
using the OSS distribution as FIPS 140 support is not available in
neither of these.
Finally, it adds some information around FIPS 140 testing in our testing
documentation reference so that developers can hopefully keep in
mind fips 140 related intricacies when writing/changing docs.
143 lines
4.1 KiB
Text
143 lines
4.1 KiB
Text
[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" : "l0ng-r4nd0m-p@ssw0rd",
|
|
"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:l0ng-r4nd0m-p@ssw0rd http://localhost:9200/_cluster/health
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|