The esusers realm is the default Shield realm. The esusers realm enables the registration of users, passwords for
those users, and associates those users with roles. The
esusers command-line tool assists with the registration and
administration of users.
Like all other realms, the
esusers realm is configured under the
shield.authc.realms settings namespace in the
elasticsearch.yml file. The following snippet shows an example of such configuration:
esusers Realm Configuration.
shield: authc: realms: default: type: esusers order: 0
esusers Realm Settings
Indicates the realm type and must be set to
Indicates the priority of this realm within the realm chain. Realms with lower order will be consulted first. Although not required, it is highly recommended to explicitly set this value when multiple realms are configured. Defaults to
Indicates whether this realm is enabled/disabled. Provides an easy way to disable realms in the chain without removing their configuration. Defaults to
Points to the location of the
Points to the location of the
Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to
Specified the maximum number of user entries that can live in the cache at a given time. Defaults to 100,000.
(Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see here for possible values).
When no realms are explicitly configured in
elasticsearch.yml, a default realm chain will be created that holds
esusers realm. If you wish to only work with
esusers realm and you’re satisfied with the default
files paths, there is no real need to add the above configuration.
esusers command line tool is located under Shield’s bin directory and enables several
administrative tasks for managing users:
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
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 an underscore (
_). Subsequent characters can be letters, underscores (
_), digits (
0-9), or any
of the following symbols
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 esusers realm. The password for this user is
theshining, and this user is associated with the
esusers useradd jacknich -p theshining -r logstash,marvel
For valid role names please see Role Definitions.
esusers list command lists the users registered in the esusers 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.
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
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>
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
marvel roles from user
jacknich, as well as adding the
esusers roles jacknich -r logstash,marvel -a user
Listing the user displays the new role assignment:
esusers list jacknich jacknich : user
esusers tool manipulates two files,
users_roles, in Shield’s
config directory. These two files store all user data for the esusers realm and are read by Shield
By default, Shield 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
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_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.
users file stores all the users and their passwords. The format of the
users file follows the format of
htpasswd file from a standard Apache webserver, where each line contains a single user entry that holds its
username and its hashed password.
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
esusers command-line tool uses
bcrypt to hash the password by default. All of the
algorithms are available as an option.
The user credentials are not stored on disk in clear text. The esusers creates a
bcrypt hashes of the passwords and
bcrypt is considered to be highly secured hash and by default it uses 10 rounds to generate the salts
it hashes with. While highly secured, it is also relatively slow. For this reason, Shield also introduce an in-memory
cache over the
esusers store. This cache can use a different hashing algorithm for storing the passwords in memeory.
The default hashing algorithm that is used is
bcrypt4 - a bcrypt algorithm that uses 4 rounds for salt generation.
We’ve seen in the table above that the cache characteristics can be configured. The following table describes the different hash algorithm that can be set:
Table 2. Cache hash algorithms
Doesn’t hash the credentials and keeps it in clear text in memory. CAUTION:
keeping clear text is considered insecure and can be compromised at the OS
level (e.g. memory dumps and
Shield exposes an API to force cached user eviction. The following example, evicts all users from the
$ curl -XPOST 'http://localhost:9200/_shield/realm/esusers/_cache/clear'
It is also possible to evict specific users:
$ curl -XPOST 'http://localhost:9200/_shield/realm/esusers/_cache/clear?usernames=rdeniro,alpacino'
Multiple realms can also be specified using comma-delimited list:
$ curl -XPOST 'http://localhost:9200/_shield/realm/esusers,ldap1/_cache/clear'