Skip to content

Adjust file realm docs #52471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 25, 2020
Merged

Adjust file realm docs #52471

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9022623
Adjust file realm docs
jkakavas Feb 18, 2020
16c4dd4
Address feedback
jkakavas Feb 20, 2020
bdf6786
Merge remote-tracking branch 'origin/master' into file-realm-docs
jkakavas Feb 20, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 13 additions & 9 deletions x-pack/docs/en/security/authentication/file-realm.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,21 @@ With the `file` realm, users are defined in local files on each node in the clus

IMPORTANT: As the administrator of the cluster, it is your responsibility to
ensure the same users are defined on every node in the cluster. The {stack}
{security-features} do not deliver any mechanism to guarantee this.
{security-features} do not deliver any mechanism to guarantee this. You should
also be aware that you cannot add or manage users in the `file` realm via the
<<security-user-apis, user APIs>> and you cannot add or manage them in {kib} on the
*Management / Security / Users* page

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.
The `file` realm is very useful as a fallback or recovery realm. For example in cases where
the cluster is unresponsive or the security index is unavailable, or when you forget the
password for your administrative users.
In this type of scenario, the `file` realm is a convenient 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.
specify are used for authentication. To use the `file` realm you must explicitly
include it in the realm chain.

To define users, the {security-features} provide the
<<users-command,users>> command-line tool. This tool enables you to add
Expand All @@ -26,4 +30,4 @@ and remove users, assign user roles, and manage user passwords.
[[file-realm-configuration]]
==== Configuring a file realm

include::configuring-file-realm.asciidoc[]
include::configuring-file-realm.asciidoc[]