Skip to content

Commit 3a97e59

Browse files
lcawllcawl
committed
[DOCS] Adds file realm configuration details (#30221)
1 parent f9c203a commit 3a97e59

File tree

3 files changed

+114
-101
lines changed

3 files changed

+114
-101
lines changed

‎x-pack/docs/en/security/authentication/configuring-file-realm.asciidoc

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
[role="xpack"]
2+
[[configuring-file-realm]]
3+
=== Configuring a file realm
4+
5+
You can manage and authenticate users with the built-in `file` internal realm.
6+
All the data about the users for the `file` realm is stored in two files on each
7+
node in the cluster: `users` and `users_roles`. Both files are located in
8+
`CONFIG_DIR/` and are read on startup.
9+
10+
[IMPORTANT]
11+
==============================
12+
The `users` and `users_roles` files are managed locally by the node and are
13+
**not** managed globally by the cluster. This means that with a typical
14+
multi-node cluster, the exact same changes need to be applied on each and every
15+
node in the cluster.
16+
17+
A safer approach would be to apply the change on one of the nodes and have the
18+
files distributed or copied to all other nodes in the cluster (either manually
19+
or using a configuration management system such as Puppet or Chef).
20+
==============================
21+
22+
The `file` realm is added to the realm chain by default. You don't need to
23+
explicitly configure a `file` realm.
24+
25+
For more information about file realms, see
26+
{xpack-ref}/file-realm.html[File-based user authentication].
27+
28+
. (Optional) Add a realm configuration of type `file` to `elasticsearch.yml`
29+
under the `xpack.security.authc.realms` namespace. At a minimum, you must set
30+
the realm `type` to `file`. If you are configuring multiple realms, you should
31+
also explicitly set the `order` attribute.
32+
+
33+
--
34+
//See <<ref-users-settings>> for all of the options you can set for a `file` realm.
35+
36+
For example, the following snippet shows a `file` realm configuration that sets
37+
the `order` to zero so the realm is checked first:
38+
39+
[source, yaml]
40+
------------------------------------------------------------
41+
xpack:
42+
security:
43+
authc:
44+
realms:
45+
file1:
46+
type: file
47+
order: 0
48+
------------------------------------------------------------
49+
--
50+
51+
. Restart {es}.
52+
53+
. Add user information to the `CONFIG_DIR/users` file on each node in the
54+
cluster.
55+
+
56+
--
57+
The `users` file stores all the users and their passwords. Each line in the file
58+
represents a single user entry consisting of the username and **hashed** password.
59+
60+
[source,bash]
61+
----------------------------------------------------------------------
62+
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
63+
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
64+
jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
65+
----------------------------------------------------------------------
66+
67+
{security} uses `bcrypt` to hash the user passwords.
68+
69+
While it is possible to modify this files directly using any standard text
70+
editor, we strongly recommend using the <<users-command>> tool to apply the
71+
required changes.
72+
73+
IMPORTANT: As the administrator of the cluster, it is your responsibility to
74+
ensure the same users are defined on every node in the cluster.
75+
{security} does not deliver any mechanism to guarantee this.
76+
77+
--
78+
79+
. Add role information to the `CONFIG_DIR/users_roles` file on each node
80+
in the cluster.
81+
+
82+
--
83+
The `users_roles` file stores the roles associated with the users. For example:
84+
85+
[source,shell]
86+
--------------------------------------------------
87+
admin:rdeniro
88+
power_user:alpacino,jacknich
89+
user:jacknich
90+
--------------------------------------------------
91+
92+
Each row maps a role to a comma-separated list of all the users that are
93+
associated with that role.
94+
95+
You can use the <<users-command>> tool to update this file. You must ensure that
96+
the same changes are made on every node in the cluster.
97+
--
98+
99+
. (Optional) Change how often the `users` and `users_roles` files are checked.
100+
+
101+
--
102+
By default, {security} checks these files for changes every 5 seconds. You can
103+
change this default behavior by changing the `resource.reload.interval.high`
104+
setting in the `elasticsearch.yml` file (as this is a common setting in {es},
105+
changing its value may effect other schedules in the system).
106+
--

‎x-pack/docs/en/security/authentication/file-realm.asciidoc

+5-100
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
[[file-realm]]
22
=== File-based User Authentication
33

4-
You can manage and authenticate users with the built-in `file` internal realm.
5-
With the `file` realm users are defined in local files on each node in the cluster.
4+
You can manage and authenticate users with the built-in `file` realm.
5+
With the `file` realm, users are defined in local files on each node in the cluster.
66

77
IMPORTANT: As the administrator of the cluster, it is your responsibility to
88
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
2020

2121
To define users, {security} provides the {ref}/users-command.html[users]
2222
command-line tool. This tool enables you to add and remove users, assign user
23-
roles and manage user passwords.
23+
roles, and manage user passwords.
2424

25-
==== Configuring a File Realm
26-
27-
The `file` realm is added to the realm chain by default. You don't need to
28-
explicitly configure a `file` realm to manage users with the `users` tool.
29-
30-
Like other realms, you can configure options for a `file` realm in the
31-
`xpack.security.authc.realms` namespace in `elasticsearch.yml`.
32-
33-
To configure an `file` realm:
34-
35-
. Add a realm configuration of type `file` to `elasticsearch.yml` under the
36-
`xpack.security.authc.realms` namespace. At a minimum, you must set the realm `type` to
37-
`file`. If you are configuring multiple realms, you should also explicitly set
38-
the `order` attribute. See <<file-realm-settings>> for all of the options you can set
39-
for a `file` realm.
40-
+
41-
For example, the following snippet shows a `file` realm configuration that sets
42-
the `order` to zero so the realm is checked first:
43-
+
44-
[source, yaml]
45-
------------------------------------------------------------
46-
xpack:
47-
security:
48-
authc:
49-
realms:
50-
file1:
51-
type: file
52-
order: 0
53-
------------------------------------------------------------
54-
55-
. Restart Elasticsearch.
56-
57-
[[file-realm-settings]]
58-
===== File Realm Settings
59-
60-
See {ref}/security-settings.html#ref-users-settings[File Realm Settings].
61-
62-
==== A Look Under the Hood
63-
64-
All the data about the users for the `file` realm is stored in two files, `users`
65-
and `users_roles`. Both files are located in `CONFIG_DIR/x-pack/` and are read
66-
on startup.
67-
68-
By default, {security} checks these files for changes every 5 seconds. You can
69-
change this default behavior by changing the `resource.reload.interval.high` setting in
70-
the `elasticsearch.yml` file (as this is a common setting in Elasticsearch,
71-
changing its value may effect other schedules in the system).
72-
73-
[IMPORTANT]
74-
==============================
75-
These files are managed locally by the node and are **not** managed
76-
globally by the cluster. This means that with a typical multi-node cluster,
77-
the exact same changes need to be applied on each and every node in the
78-
cluster.
79-
80-
A safer approach would be to apply the change on one of the nodes and have the
81-
`users` and `users_roles` files distributed/copied to all other nodes in the
82-
cluster (either manually or using a configuration management system such as
83-
Puppet or Chef).
84-
==============================
85-
86-
While it is possible to modify these files directly using any standard text
87-
editor, we strongly recommend using the {ref}/users-command.html[`bin/elasticsearch-users`]
88-
command-line tool to apply the required changes.
89-
90-
[float]
91-
[[users-file]]
92-
===== The `users` File
93-
The `users` file stores all the users and their passwords. Each line in the
94-
`users` file represents a single user entry consisting of the username and
95-
**hashed** password.
96-
97-
[source,bash]
98-
----------------------------------------------------------------------
99-
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
100-
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
101-
jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
102-
----------------------------------------------------------------------
103-
104-
NOTE: {security} uses `bcrypt` to hash the user passwords.
105-
106-
[float]
107-
[[users_defining-roles]]
108-
==== The `users_roles` File
109-
110-
The `users_roles` file stores the roles associated with the users, as in the
111-
following example:
112-
113-
[source,shell]
114-
--------------------------------------------------
115-
admin:rdeniro
116-
power_user:alpacino,jacknich
117-
user:jacknich
118-
--------------------------------------------------
119-
120-
Each row maps a role to a comma-separated list of all the users that are
121-
associated with that role.
25+
For more information, see
26+
{ref}/configuring-file-realm.html[Configuring a file realm].

‎x-pack/docs/en/security/configuring-es.asciidoc

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[role="xpack"]
22
[[configuring-security]]
3-
== Configuring Security in {es}
3+
== Configuring security in {es}
44
++++
55
<titleabbrev>Configuring Security</titleabbrev>
66
++++
@@ -72,6 +72,7 @@ user API.
7272

7373
. Choose which types of realms you want to use to authenticate users.
7474
** <<configuring-ad-realm,Configure an Active Directory realm>>.
75+
** <<configuring-file-realm,Configure a file realm>>.
7576
** <<configuring-pki-realm,Configure a PKI realm>>.
7677

7778
. Set up roles and users to control access to {es}.
@@ -133,6 +134,7 @@ include::securing-communications/configuring-tls-docker.asciidoc[]
133134
include::securing-communications/enabling-cipher-suites.asciidoc[]
134135
include::securing-communications/separating-node-client-traffic.asciidoc[]
135136
include::authentication/configuring-active-directory-realm.asciidoc[]
137+
include::authentication/configuring-file-realm.asciidoc[]
136138
include::authentication/configuring-pki-realm.asciidoc[]
137139
include::{xes-repo-dir}/settings/security-settings.asciidoc[]
138140
include::{xes-repo-dir}/settings/audit-settings.asciidoc[]

0 commit comments

Comments
 (0)