WARNING: Version 6.0 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.
File-based User Authentication
editFile-based User Authentication
editYou can manage and authenticate users with the built-in file
internal realm.
With the file
realm users are defined in local files on each node in the cluster.
As the administrator of the cluster, it is your responsibility to ensure the same users are defined on every node in the cluster. X-Pack security does not deliver any mechanism to guarantee this.
The file
realm is primarily supported to serve as a fallback/recovery realm. It
is mostly useful in situations where all users locked themselves out of the system
(no one remembers their username/password). In this type of scenarios, the file
realm is your only way out - you can define a new admin
user in the file
realm
and use it to log in and reset the credentials of all other users.
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.
To define users, X-Pack security provides the users command-line tool. This tool enables you to add and remove users, assign user roles and manage user passwords.
Configuring a File 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 users
tool.
Like other realms, you can configure options for a file
realm in the
xpack.security.authc.realms
namespace in elasticsearch.yml
.
To configure an file
realm:
-
Add a realm configuration of type
file
toelasticsearch.yml
under thexpack.security.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 a
file
realm configuration that sets theorder
to zero so the realm is checked first:xpack: security: 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 |
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). |
A Look Under the Hood
editAll the data about the users for the file
realm is stored in two files, users
and users_roles
. Both files are located in ES_PATH_CONF/x-pack/
and are read
on startup.
By default, X-Pack security checks these files for changes every 5 seconds. You can
change this default behavior by changing the resource.reload.interval.high
setting in
the elasticsearch.yml
file (as this is a common setting in Elasticsearch,
changing its value may effect other schedules in the system).
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 bin/x-pack/users
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
X-Pack security uses bcrypt
to hash the user passwords.
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.