From 9022623fb9950b794961fbb1de66723b5150cfee Mon Sep 17 00:00:00 2001 From: Ioannis Kakavas Date: Tue, 18 Feb 2020 13:48:47 +0200 Subject: [PATCH 1/2] Adjust file realm docs The existing wording in the file realm docs proved confusing for users as it seemed to indicate that it should _only_ be used as a fallback/recovery realm and that it is not a first class realm. This change attempts to clarify this and point out that recovery is _a_ use case for the file realm but not the only intended one. --- .../security/authentication/file-realm.asciidoc | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/x-pack/docs/en/security/authentication/file-realm.asciidoc b/x-pack/docs/en/security/authentication/file-realm.asciidoc index f0549a477cd8a..5c1716cbccfab 100644 --- a/x-pack/docs/en/security/authentication/file-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/file-realm.asciidoc @@ -9,15 +9,16 @@ 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. -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/recovery realm, for instance 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 scenarios, 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 <> command-line tool. This tool enables you to add @@ -26,4 +27,4 @@ and remove users, assign user roles, and manage user passwords. [[file-realm-configuration]] ==== Configuring a file realm -include::configuring-file-realm.asciidoc[] \ No newline at end of file +include::configuring-file-realm.asciidoc[] From 16c4dd42d989754293bfb371f4c4087accb4bca0 Mon Sep 17 00:00:00 2001 From: Ioannis Kakavas Date: Thu, 20 Feb 2020 12:44:32 +0200 Subject: [PATCH 2/2] Address feedback --- .../docs/en/security/authentication/file-realm.asciidoc | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/x-pack/docs/en/security/authentication/file-realm.asciidoc b/x-pack/docs/en/security/authentication/file-realm.asciidoc index 5c1716cbccfab..d3528e62b32d2 100644 --- a/x-pack/docs/en/security/authentication/file-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/file-realm.asciidoc @@ -7,12 +7,15 @@ 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 +<> and you cannot add or manage them in {kib} on the +*Management / Security / Users* page -The `file` realm is very useful as a fallback/recovery realm, for instance in cases where +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 scenarios, the `file` realm is a convenient way out - you can +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.