147 lines
6.5 KiB
Plaintext
147 lines
6.5 KiB
Plaintext
[[file-realm]]
|
|
=== File-based User Authentication
|
|
|
|
You 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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
IMPORTANT: 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, {security} provides the {ref}/users-command.html[users]
|
|
command-line tool. This tool enables you to add and remove users, assign user
|
|
roles and manage user passwords.
|
|
|
|
==== Configuring a File Realm
|
|
|
|
The `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` 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 <<file-realm-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 Elasticsearch.
|
|
|
|
[[file-realm-settings]]
|
|
===== File Realm Settings
|
|
|
|
[cols="4,^3,10"]
|
|
|=======================
|
|
| Setting | Required | Description
|
|
| `type` | yes | Indicates the realm type. Must be set to `file`.
|
|
| `order` | 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
|
|
`Integer.MAX_VALUE`.
|
|
| `enabled` | no | Indicates whether this realm is enabled or
|
|
disabled. Enables you to disable a realm without
|
|
removing its configuration. Defaults to `true`.
|
|
| `cache.ttl` | 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 {ref}/common-options.html#time-units[time units].
|
|
Defaults to `20m`.
|
|
| `cache.max_users` | no | Specifies the maximum number of user entries that
|
|
can be stored in the cache at one time. Defaults
|
|
to 100,000.
|
|
| `cache.hash_algo` | no | Specifies the hashing algorithm that is used for
|
|
the cached user credentials. See <<cache-hash-algo,
|
|
Cache hash algorithms>> for the possible values.
|
|
(Expert Setting).
|
|
|=======================
|
|
|
|
==== A Look Under the Hood
|
|
|
|
All the data about the users for the `file` realm is stored in two files, `users`
|
|
and `users_roles`. Both files are located in `CONFIG_DIR/x-pack/` 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 `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).
|
|
|
|
[IMPORTANT]
|
|
==============================
|
|
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 {ref}/users-command.html[`bin/x-pack/users`]
|
|
command-line tool to apply the required changes.
|
|
|
|
[float]
|
|
[[users-file]]
|
|
===== The `users` File
|
|
The `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.
|
|
|
|
[source,bash]
|
|
----------------------------------------------------------------------
|
|
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
|
|
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
|
|
jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
|
|
----------------------------------------------------------------------
|
|
|
|
NOTE: {security} uses `bcrypt` to hash the user passwords.
|
|
|
|
[float]
|
|
[[users_defining-roles]]
|
|
==== The `users_roles` File
|
|
|
|
The `users_roles` file stores the roles associated with the users, as in the
|
|
following 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.
|