[[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 <> 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 <> 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.