106 lines
3.9 KiB
Plaintext
106 lines
3.9 KiB
Plaintext
|
[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
|
||
|
|
`CONFIG_DIR/` and are read on startup.
|
||
|
|
|
||
|
|
[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].
|
||
|
|
|
||
|
|
. (Optional) Add a realm configuration of type `file` to `elasticsearch.yml`
|
||
|
|
under the `xpack.security.authc.realms` namespace. At a minimum, you must set
|
||
|
|
the realm `type` to `file`. If you are configuring multiple realms, you should
|
||
|
|
also explicitly set the `order` attribute.
|
||
|
|
+
|
||
|
|
--
|
||
|
|
//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:
|
||
|
|
file1:
|
||
|
|
type: file
|
||
|
|
order: 0
|
||
|
|
------------------------------------------------------------
|
||
|
|
--
|
||
|
|
|
||
|
|
. Restart {es}.
|
||
|
|
|
||
|
|
. Add user information to the `CONFIG_DIR/users` file on each node in the
|
||
|
|
cluster.
|
||
|
|
+
|
||
|
|
--
|
||
|
|
The `users` file stores all the users and their passwords. Each line in the file
|
||
|
|
represents a single user entry consisting of the username and **hashed** password.
|
||
|
|
|
||
|
|
[source,bash]
|
||
|
|
----------------------------------------------------------------------
|
||
|
|
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
|
||
|
|
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
|
||
|
|
jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
|
||
|
|
----------------------------------------------------------------------
|
||
|
|
|
||
|
|
{security} uses `bcrypt` to hash the user passwords.
|
||
|
|
|
||
|
|
While it is possible to modify this files directly using any standard text
|
||
|
|
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.
|
||
|
|
{security} does not deliver any mechanism to guarantee this.
|
||
|
|
|
||
|
|
--
|
||
|
|
|
||
|
|
. Add role information to the `CONFIG_DIR/users_roles` file on each node
|
||
|
|
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.
|
||
|
|
+
|
||
|
|
--
|
||
|
|
By default, {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 {es},
|
||
|
|
changing its value may effect other schedules in the system).
|
||
|
|
--
|