File-based User Authentication
editFile-based User Authentication
editYou can manage and authenticate users with the built-in file
realm.
A file realm is created by default when you install Shield. You use the
esusers command line tool to add and remove users, assign user roles,
and manage user passwords.
As of 2.3.0
the REST APIs and the native
realm are the preferred way to
manage users. For more information, see Native User
Authentication. The file
realm (formerly called esusers
) is still
supported and now functions as a fallback/recovery realm. For example, if all
users lock themselves out of the system (no one remembers their username and
password), you can define an admin
user in the file
realm and use those
credentials to restore access.
When you configure realms in elasticsearch.yml
, only the realms
you specify are used for authentication. To use the file
realm as
a fallback, you must include it in the realm chain.
Configuring a File-based Realm
editThe file realm is added to the realm chain by default. You don’t need to explicitly
configure a file realm to manage users with the esusers
tool.
Like other realms, you can configure options for a file
realm in the
shield.authc.realms
namespace in elasticsearch.yml
.
To configure an esusers realm:
-
Add a realm configuration of type
file
toelasticsearch.yml
in theshield.authc.realms
namespace. At a minimum, you must set the realmtype
tofile
. If you are configuring multiple realms, you should also explicitly set theorder
attribute. See File Realm Settings for all of the options you can set for afile
realm.For example, the following snippet shows an
file
realm configuration that sets theorder
to zero so the realm is checked first:shield: authc: realms: file1: type: file order: 0
- Restart Elasticsearch.
File 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 |
Points to the location
of the |
|
no |
Points to the location
of the |
|
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 Users in a File-based Realm
editAs of 2.3.0
the REST APIs and the native
realm are the preferred way to manage users.
For more information, see Native User Authentication.
The file
realm (formerly called esusers
) is still supported and now functions as a
fallback/recovery realm. For example, if all users lock themselves out of the system
(no one remembers their username and password), you can define an admin
user in the
file
realm and use those credentials to restore access.
The esusers
command line tool is located in ES_HOME/bin/shield
and enables several
administrative tasks for managing users:
Adding Users
editThe esusers useradd
command adds a user to your cluster.
To ensure that Elasticsearch can read the user and role information at startup, run esusers useradd
as the
same user you use to run Elasticsearch. Running the command as root or some other user will update the permissions
for the users
and users_roles
files and prevent Elasticsearch from accessing them.
esusers useradd <username>
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 $
You can specify the user’s password at the command line with the -p
option. When this option is absent, the
esusers
command prompts you for the password. Omit the -p
option to keep plaintext passwords out of the terminal
session’s command history.
esusers useradd <username> -p <secret>
Passwords must be at least 6 characters long.
You can define a user’s roles with the -r
parameter. This parameter accepts a comma-separated list of role names to
associate with the user.
esusers useradd <username> -r <comma-separated list of role names>
The following example adds a new user named jacknich
to the file
realm. The password for this user is
theshining
, and this user is associated with the logstash
and marvel
roles.
esusers useradd jacknich -p theshining -r logstash,marvel
For valid role names please see Role Definitions.
Listing Users
editThe esusers list
command lists the users registered in the file
realm, as in the following example:
esusers list rdeniro : admin alpacino : power_user jacknich : marvel,logstash
Users are in the left-hand column and their corresponding roles are listed in the right-hand column.
The esusers list <username>
command lists a specific user. Use this command to verify that a user has been
successfully added to the cluster.
esusers list jacknich jacknich : marvel,logstash
Managing User Passwords
editThe esusers passwd
command enables you to reset a user’s password. You can specify the new password directly with the
-p
option. When -p
option is omitted, the tool will prompt you to enter and confirm a password in interactive mode.
esusers passwd <username>
esusers passwd <username> -p <password>
Assigning Users to Roles
editThe esusers roles
command manages the roles associated to a particular user. The -a
option adds a comma-separated
list of roles to a user. The -r
option removes a comma-separated list of roles from a user. You can combine adding and
removing roles within the same command to change a user’s roles.
esusers roles <username> -a <commma-separate list of roles> -r <commma-separate list of roles>
The following command removes the logstash
and marvel
roles from user jacknich
, as well as adding the user
role:
esusers roles jacknich -r logstash,marvel -a user
Listing the user displays the new role assignment:
esusers list jacknich jacknich : user
Deleting Users
editThe esusers userdel
command deletes a user.
userdel <username>
About esusers
editThe esusers
tool manipulates two files, users
and users_roles
, in CONFIG_DIR/shield/
. These two files store all user data for the file
realm and are read on startup.
By default, Security checks these files for changes every 5 seconds. You can change this default behavior by changing the
value of the watcher.interval.high
setting in the elasticsearch.yml
file.
These files are managed locally by the node and are not managed globally by the cluster. This means that with a typical multi-node cluster, the exact same changes need to be applied on each and every node in the cluster.
A safer approach would be to apply the change on one of the nodes and have the
users
and users_roles
files distributed/copied to all other nodes in the
cluster (either manually or using a configuration management system such as
Puppet or Chef).
While it is possible to modify these files directly using any standard text
editor, we strongly recommend using the esusers
command-line tool to apply
the required changes.
The users
File
editThe users
file stores all the users and their passwords. Each line in the users
file represents a single user entry
consisting of the username and hashed password.
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
The esusers
command-line tool uses bcrypt
to hash the password by default.
The users_roles
File
editThe users_roles
file stores the roles associated with the users, as in the following example:
admin:rdeniro power_user:alpacino,jacknich user:jacknich
Each row maps a role to a comma-separated list of all the users that are associated with that role.