mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-17 10:25:15 +00:00
[DOCS] Adds file realm configuration details (#30221)
This commit is contained in:
Lisa Cawley
GitHub
parent
86addc0c8b
commit
db44a4cddb
@ -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 <<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).
|
||||
--
|
||||
@ -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 <<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
|
||||
|
||||
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].
|
||||
@ -1,6 +1,6 @@
|
||||
[role="xpack"]
|
||||
[[configuring-security]]
|
||||
== Configuring Security in {es}
|
||||
== Configuring security in {es}
|
||||
++++
|
||||
<titleabbrev>Configuring Security</titleabbrev>
|
||||
++++
|
||||
@ -72,6 +72,7 @@ user API.
|
||||
|
||||
. Choose which types of realms you want to use to authenticate users.
|
||||
** <<configuring-ad-realm,Configure an Active Directory realm>>.
|
||||
** <<configuring-file-realm,Configure a file realm>>.
|
||||
** <<configuring-pki-realm,Configure a PKI realm>>.
|
||||
|
||||
. 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[]
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user