[[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 <> 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). |======================= [[managing-file-users]] ==== Managing Users The `users` command-line tool is located in `ES_HOME/bin/x-pack` and enables several administrative tasks for managing users: * <> * <> * <> * <> * <> [[file-realm-add-user]] ===== Adding Users Use the `useradd` sub-command to add a user to your local node. NOTE: To ensure that Elasticsearch can read the user and role information at startup, run `users useradd` as the same user you use to run Elasticsearch. Running the command as root or some other user will update the permissions for the `users` and `users_roles` files and prevent Elasticsearch from accessing them. [source,shell] ---------------------------------------- bin/x-pack/users useradd ---------------------------------------- Usernames must be at least 1 and no more than 1024 characters. They can contain alphanumeric characters (`a-z`, `A-Z`, `0-9`), spaces, punctuation, and printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)[Basic Latin (ASCII) block]. Leading or trailing whitespace is not allowed. You can specify the user's password at the command-line with the `-p` option. When this option is absent, the command prompts you for the password. Omit the `-p` option to keep plaintext passwords out of the terminal session's command history. [source,shell] ---------------------------------------------------- bin/x-pack/users useradd -p ---------------------------------------------------- Passwords must be at least 6 characters long. You can define a user's roles with the `-r` option. This option accepts a comma-separated list of role names to assign to the user. [source,shell] ------------------------------------------------------------------- bin/x-pack/users useradd -r ------------------------------------------------------------------- The following example adds a new user named `jacknich` to the `file` realm. The password for this user is `theshining`, and this user is associated with the `network` and `monitoring` roles. [source,shell] ------------------------------------------------------------------- bin/x-pack/users useradd jacknich -p theshining -r network,monitoring ------------------------------------------------------------------- For valid role names please see <>. [[file-realm-list-users]] ===== Listing Users Use the `list` sub-command to list the users registered with the `file` realm on the local node. [source, shell] ---------------------------------- bin/x-pack/users list rdeniro : admin alpacino : power_user jacknich : monitoring,network ---------------------------------- Users are in the left-hand column and their corresponding roles are listed in the right-hand column. The `list ` sub-command lists a specific user. Use this command to verify that a user was successfully added to the local `file` realm. [source,shell] ----------------------------------- bin/x-pack/users list jacknich jacknich : monitoring,network ----------------------------------- [[file-realm-manage-passwd]] ===== Managing User Passwords Use the `passwd` sub-command to reset a user's password. You can specify the new password directly with the `-p` option. When `-p` option is omitted, the tool will prompt you to enter and confirm a password in interactive mode. [source,shell] -------------------------------------------------- bin/x-pack/users passwd -------------------------------------------------- [source,shell] -------------------------------------------------- bin/x-pack/users passwd -p -------------------------------------------------- [[file-realm-manage-roles]] ===== Assigning Users to Roles Use the `roles` sub-command to manage the roles of a particular user. The `-a` option adds a comma-separated list of roles to a user. The `-r` option removes a comma-separated list of roles from a user. You can combine adding and removing roles within the same command to change a user's roles. [source,shell] ------------------------------------------------------------------------------------------------------------ bin/x-pack/users roles -a -r ------------------------------------------------------------------------------------------------------------ The following command removes the `network` and `monitoring` roles from user `jacknich` and adds the `user` role: [source,shell] ------------------------------------------------------------ bin/x-pack/users roles jacknich -r network,monitoring -a user ------------------------------------------------------------ Listing the user displays the new role assignment: [source,shell] --------------------------------- bin/x-pack/users list jacknich jacknich : user --------------------------------- [[file-realm-remove-user]] ===== Deleting Users Use the `userdel` sub-command to delete a user. [source,shell] -------------------------------------------------- bin/x-pack/users userdel -------------------------------------------------- ==== 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 `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.