diff --git a/x-pack/docs/en/security/authentication/configuring-file-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-file-realm.asciidoc new file mode 100644 index 0000000000000..8555902e503d3 --- /dev/null +++ b/x-pack/docs/en/security/authentication/configuring-file-realm.asciidoc @@ -0,0 +1,106 @@ +[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 <> 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 <> 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 <> 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). +-- \ No newline at end of file diff --git a/x-pack/docs/en/security/authentication/file-realm.asciidoc b/x-pack/docs/en/security/authentication/file-realm.asciidoc index 000e204f67f5e..937537ac1a11f 100644 --- a/x-pack/docs/en/security/authentication/file-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/file-realm.asciidoc @@ -1,8 +1,8 @@ [[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. +You can manage and authenticate users with the built-in `file` 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. @@ -20,102 +20,7 @@ realms you specify are used for authentication. To use the 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. +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 - -See {ref}/security-settings.html#ref-users-settings[File Realm Settings]. - -==== 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/elasticsearch-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. +For more information, see +{ref}/configuring-file-realm.html[Configuring a file realm]. \ No newline at end of file diff --git a/x-pack/docs/en/security/configuring-es.asciidoc b/x-pack/docs/en/security/configuring-es.asciidoc index 81e9007d7500c..114fd1cdc4f15 100644 --- a/x-pack/docs/en/security/configuring-es.asciidoc +++ b/x-pack/docs/en/security/configuring-es.asciidoc @@ -1,6 +1,6 @@ [role="xpack"] [[configuring-security]] -== Configuring Security in {es} +== Configuring security in {es} ++++ Configuring Security ++++ @@ -72,6 +72,7 @@ user API. . Choose which types of realms you want to use to authenticate users. ** <>. +** <>. ** <>. . Set up roles and users to control access to {es}. @@ -133,6 +134,7 @@ include::securing-communications/configuring-tls-docker.asciidoc[] include::securing-communications/enabling-cipher-suites.asciidoc[] include::securing-communications/separating-node-client-traffic.asciidoc[] include::authentication/configuring-active-directory-realm.asciidoc[] +include::authentication/configuring-file-realm.asciidoc[] include::authentication/configuring-pki-realm.asciidoc[] include::{xes-repo-dir}/settings/security-settings.asciidoc[] include::{xes-repo-dir}/settings/audit-settings.asciidoc[]