2018-05-01 17:11:38 -04:00
|
|
|
[role="xpack"]
|
|
|
|
[[configuring-file-realm]]
|
|
|
|
=== Configuring a file realm
|
|
|
|
|
|
|
|
You can manage and authenticate users with the built-in `file` internal realm.
|
|
|
|
All the data about the users for the `file` realm is stored in two files on each
|
|
|
|
node in the cluster: `users` and `users_roles`. Both files are located in
|
2018-06-28 11:27:04 -04:00
|
|
|
`ES_PATH_CONF` and are read on startup.
|
2018-05-01 17:11:38 -04:00
|
|
|
|
|
|
|
[IMPORTANT]
|
|
|
|
==============================
|
|
|
|
The `users` and `users_roles` 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
|
|
|
|
files distributed or copied to all other nodes in the cluster (either manually
|
|
|
|
or using a configuration management system such as Puppet or Chef).
|
|
|
|
==============================
|
|
|
|
|
|
|
|
The `file` realm is added to the realm chain by default. You don't need to
|
|
|
|
explicitly configure a `file` realm.
|
|
|
|
|
|
|
|
For more information about file realms, see
|
|
|
|
{xpack-ref}/file-realm.html[File-based user authentication].
|
|
|
|
|
2018-11-05 22:56:50 -05:00
|
|
|
. (Optional) Add a realm configuration to `elasticsearch.yml` under the
|
|
|
|
`xpack.security.authc.realms.file` namespace. At a minimum, you must set
|
|
|
|
the realm's `order` attribute.
|
2018-05-01 17:11:38 -04:00
|
|
|
+
|
|
|
|
--
|
|
|
|
//See <<ref-users-settings>> for all of the options you can set for a `file` realm.
|
|
|
|
|
|
|
|
For example, the following snippet shows a `file` realm configuration that sets
|
|
|
|
the `order` to zero so the realm is checked first:
|
|
|
|
|
|
|
|
[source, yaml]
|
|
|
|
------------------------------------------------------------
|
|
|
|
xpack:
|
|
|
|
security:
|
|
|
|
authc:
|
|
|
|
realms:
|
2018-11-05 22:56:50 -05:00
|
|
|
file:
|
|
|
|
file1:
|
|
|
|
order: 0
|
2018-05-01 17:11:38 -04:00
|
|
|
------------------------------------------------------------
|
|
|
|
--
|
|
|
|
|
|
|
|
. Restart {es}.
|
|
|
|
|
2018-06-28 11:27:04 -04:00
|
|
|
. Add user information to the `ES_PATH_CONF/users` file on each node in the
|
2018-05-01 17:11:38 -04:00
|
|
|
cluster.
|
|
|
|
+
|
|
|
|
--
|
|
|
|
The `users` file stores all the users and their passwords. Each line in the file
|
2018-08-21 05:05:42 -04:00
|
|
|
represents a single user entry consisting of the username and **hashed** and **salted** password.
|
2018-05-01 17:11:38 -04:00
|
|
|
|
|
|
|
[source,bash]
|
|
|
|
----------------------------------------------------------------------
|
|
|
|
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
|
|
|
|
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
|
2018-08-21 05:05:42 -04:00
|
|
|
jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg=
|
2018-05-01 17:11:38 -04:00
|
|
|
----------------------------------------------------------------------
|
|
|
|
|
2018-08-21 05:05:42 -04:00
|
|
|
NOTE: To limit exposure to credential theft and mitigate credential compromise,
|
|
|
|
the file realm stores passwords and caches user credentials according to
|
|
|
|
security best practices. By default, a hashed version of user credentials
|
|
|
|
is stored in memory, using a salted `sha-256` hash algorithm and a hashed
|
|
|
|
version of passwords is stored on disk salted and hashed with the `bcrypt`
|
|
|
|
hash algorithm. To use different hash algorithms, see <<hashing-settings>>.
|
2018-05-01 17:11:38 -04:00
|
|
|
|
2018-08-21 05:05:42 -04:00
|
|
|
While it is possible to modify the `users` files directly using any standard text
|
2018-05-01 17:11:38 -04:00
|
|
|
editor, we strongly recommend using the <<users-command>> tool to apply the
|
|
|
|
required changes.
|
|
|
|
|
|
|
|
IMPORTANT: As the administrator of the cluster, it is your responsibility to
|
|
|
|
ensure the same users are defined on every node in the cluster.
|
2018-12-19 17:53:37 -05:00
|
|
|
The {es} {security-features} do not deliver any mechanisms to
|
|
|
|
guarantee this.
|
2018-05-01 17:11:38 -04:00
|
|
|
|
|
|
|
--
|
|
|
|
|
2018-06-28 11:27:04 -04:00
|
|
|
. Add role information to the `ES_PATH_CONF/users_roles` file on each node
|
2018-05-01 17:11:38 -04:00
|
|
|
in the cluster.
|
|
|
|
+
|
|
|
|
--
|
|
|
|
The `users_roles` file stores the roles associated with the users. For example:
|
|
|
|
|
|
|
|
[source,shell]
|
|
|
|
--------------------------------------------------
|
|
|
|
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.
|
|
|
|
|
|
|
|
You can use the <<users-command>> tool to update this file. You must ensure that
|
|
|
|
the same changes are made on every node in the cluster.
|
|
|
|
--
|
|
|
|
|
|
|
|
. (Optional) Change how often the `users` and `users_roles` files are checked.
|
|
|
|
+
|
|
|
|
--
|
2018-12-19 17:53:37 -05:00
|
|
|
By default, {es} checks these files for changes every 5 seconds. You can
|
2018-05-01 17:11:38 -04:00
|
|
|
change this default behavior by changing the `resource.reload.interval.high`
|
|
|
|
setting in the `elasticsearch.yml` file (as this is a common setting in {es},
|
|
|
|
changing its value may effect other schedules in the system).
|
2018-08-21 05:05:42 -04:00
|
|
|
--
|