Native User Authentication
editNative User Authentication
editThe easiest way to manage and authenticate users is with the internal native
realm.
You use the REST APIs 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.
You can, however, configure options for an native
realm in the
shield.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
the cache options.
To configure a native realm:
-
Add a realm configuration of type
native
toelasticsearch.yml
in theshield.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 annative
realm.For example, the following snippet shows an
native
realm configuration that sets theorder
to zero so the realm is checked first:shield: authc: realms: native1: type: native order: 0
- Restart Elasticsearch.
Native Realm Settings
editSetting |
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.
Enables you to disable a realm without removing its
configuration. Defaults 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 stored in the cache at one 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 Users API.
Adding Native Users
editTo add or update a user, submit a PUT or POST request to the /_shield/user/<username>
endpoint. A username must be at least 1 character 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 /_shield/user/ironman { "password" : "j@rV1s", "roles" : [ "admin", "other_role1" ], "full_name" : "Tony Stark", "email" : "tony@starkcorp.co", "metadata" : { "intelligence" : 7 } }
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 privileges. |
|
The user’s full name. Optional. |
|
The user’s email address. Optional. |
|
Arbirtary metadata you want to associate with the user. Optional. |
If you are updating a user, you can omit the password
field unless you want to change
the user’s password. You must specify the user’s roles. Omitting the optional full_name
, email
, or metadata
fields sets those values to null
.
A successful call returns a JSON structure that shows whether the user has been created or updated.
Retrieving Native Users
editTo retrieve all users, submit a GET request to the /_shield/user
endpoint:
GET /_shield/user
To retrieve particular users, specify the users as a comma-separated list:
GET /_shield/user/ironman,hulk
An array of users is returned that contains the JSON representation of each user. Note that user passwords are not included.
{ "found" : true, "users" : [ { "username" : "ironman", "roles" : [ "admin", "other_role1" ], "full_name" : "Tony Stark", "email" : "tony@starkcorp.co", "metadata" : { "intelligence" : 7 } } } ] }
Deleting Native Users
editTo delete a user, submit a DELETE request to the /_shield/user/<username>
endpoint:
DELETE /_shield/user/ironman
If the user is successfully deleted, the request returns {"found": true}
.
Otherwise, found
is set to false.
{ "found" : true }