WARNING: Version 5.5 of the Elastic Stack has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Native User Authentication
editNative User Authentication
editThe easiest way to manage and authenticate users is with the internal native
realm. You can use the REST APIs or Kibana to add and remove users, assign user roles, and
manage user passwords.
Configuring a Native Realm
editThe native realm is added to the realm chain by default. You don’t need to explicitly configure a native realm to manage users through the REST APIs.
When you configure realms in elasticsearch.yml
, only the
realms you specify are used for authentication. To use the
native
realm as a fallback, you must include it in the realm chain.
You can, however, configure options for the native
realm in the
xpack.security.authc.realms
namespace in elasticsearch.yml
. Explicitly
configuring a native realm enables you to set the order in which it appears in
the realm chain, temporary disable the realm, and control its cache options.
To configure a native realm:
-
Add a realm configuration of type
native
toelasticsearch.yml
under thexpack.security.authc.realms
namespace. At a minimum, you must set the realmtype
tonative
. If you are configuring multiple realms, you should also explicitly set theorder
attribute. See Native Realm Settings for all of the options you can set for thenative
realm.For example, the following snippet shows a
native
realm configuration that sets theorder
to zero so the realm is checked first:xpack: security: authc: realms: native1: type: native order: 0
- Restart Elasticsearch.
Table 4. Native Realm Settings
Setting | Required | Description |
---|---|---|
|
yes |
Indicates the realm type. Must be set to |
|
no |
Indicates the priority of this realm within
the realm chain. Realms with a lower order
are consulted first. Although not required,
we recommend explicitly setting this value
when you configure multiple realms. Defaults
to |
|
no |
Indicates whether this realm is enabled or
disabled. When set to |
|
no |
Specifies the time-to-live for cached user
entries. A user’s credentials are cached for
this period of time. Specify the time period
using the standard Elasticsearch
time units.
Defaults to |
|
no |
Specifies the maximum number of user entries that can be cached at any given time. Defaults to 100,000. |
|
no |
Specifies the hashing algorithm that is used for the cached user credentials. See Cache hash algorithms for the possible values. (Expert Setting) |
Managing Native Users
editYou manage users in the native
realm through the
user API.
To migrate file-based users to the native
realm, use the
migrate tool.
Adding Users
editTo add a user, submit a PUT or POST request to the /_xpack/security/user/<username>
endpoint. A username must be at least 1 character long and no longer than 30
characters. The first character must be a letter (a-z
or A-Z
) or an
underscore (_
). Subsequent characters can be letters, underscores (_
),
digits (0-9
), or any of the following symbols @
, -
, .
or $
.
POST /_xpack/security/user/jacknich { "password" : "j@rV1s", "roles" : [ "admin", "other_role1" ], "full_name" : "Jack Nicholson", "email" : "jacknich@example.com", "metadata" : { "intelligence" : 7 }, "enabled": true }
You must specify a password when adding a user. Passwords must be at least 6 characters long. |
|
You must assign at least one role to the user. The roles determine the user’s access permissions. |
|
The user’s full name. Optional. |
|
The user’s email address. Optional. |
|
Arbitrary metadata you want to associate with the user. Optional. |
|
Specifies whether the user should be enabled. Optional with a default of true. |
Retrieving Users
editTo retrieve all users, submit a GET request to the /_xpack/security/user
endpoint:
GET /_xpack/security/user
To retrieve particular users, specify the users as a comma-separated list:
GET /_xpack/security/user/jacknich,rdeniro
An object is returned holding the found users, each keyed by the relevant username. Note that user passwords are not included.
{ "jacknich" : { "username": "jacknich", "roles" : [ "admin", "other_role1" ], "full_name" : "Jack Nicholson", "email" : "jacknich@example.com", "enabled" : true, "metadata" : { "intelligence" : 7 } } }
Deleting Users
editTo delete a user, submit a DELETE request to the /_xpack/security/user/<username>
endpoint:
DELETE /_xpack/security/user/jacknich
If the user is successfully deleted, the request returns {"found": true}
.
Otherwise, found
is set to false.
{ "found" : true }