From 702c1df049e1b5d983275dc9a58637965e580dad Mon Sep 17 00:00:00 2001 From: lcawley Date: Fri, 27 Apr 2018 12:00:47 -0700 Subject: [PATCH 1/3] [DOCS] Adds native realm configuration details --- .../configuring-native-realm.asciidoc | 44 +++++++++++++++++++ .../authentication/native-realm.asciidoc | 37 +--------------- .../docs/en/security/configuring-es.asciidoc | 2 + 3 files changed, 47 insertions(+), 36 deletions(-) create mode 100644 x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc diff --git a/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc new file mode 100644 index 0000000000000..66a86cc75aefa --- /dev/null +++ b/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc @@ -0,0 +1,44 @@ +[role="xpack"] +[[configuring-native-realm]] +=== Configuring a Native Realm + +The easiest way to manage and authenticate users is with the internal `native` +realm. You don't need to explicitly configure a native realm; it is added to the +realm chain by default. + +IMPORTANT: When you configure realms in `elasticsearch.yml`, only the +realms you specify are used for authentication. To use the +`native` realm as a fallback, you must include it in the realm chain. + +You can configure options for the `native` realm in the +`xpack.security.authc.realms` namespace in `elasticsearch.yml`. Explicitly +configuring a native realm enables you to set the order in which it appears in +the realm chain, temporarily disable the realm, and control its cache options. + +. Add a realm configuration of type `native` to `elasticsearch.yml` under the +`xpack.security.authc.realms` namespace. At a minimum, you must set the realm +`type` to `native`. If you are configuring multiple realms, you should also +explicitly set the `order` attribute. ++ +-- +//See <> for all of the options you can set for the `native` realm. +For example, the following snippet shows a `native` realm configuration that +sets the `order` to zero so the realm is checked first: + +[source, yaml] +------------------------------------------------------------ +xpack: + security: + authc: + realms: + native1: + type: native + order: 0 +------------------------------------------------------------ +-- + +. Restart {es}. + +. Manage your users in {kib} on the *Management / Security / Users* page. +Alternatively, use the <>. + diff --git a/x-pack/docs/en/security/authentication/native-realm.asciidoc b/x-pack/docs/en/security/authentication/native-realm.asciidoc index 1c3afdacdc5c1..486a7725b0c9e 100644 --- a/x-pack/docs/en/security/authentication/native-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/native-realm.asciidoc @@ -9,42 +9,7 @@ manage user passwords. [float] ==== Configuring a native realm -The native realm is added to the realm chain by default. You don't need to -explicitly configure a native realm to manage users through the REST APIs. - - -IMPORTANT: When you configure realms in `elasticsearch.yml`, only the -realms you specify are used for authentication. To use the -`native` realm as a fallback, you must include it in the realm chain. - -You can, however, configure options for the `native` realm in the -`xpack.security.authc.realms` namespace in `elasticsearch.yml`. Explicitly -configuring a native realm enables you to set the order in which it appears in -the realm chain, temporary disable the realm, and control its cache options. - -To configure a native realm: - -. Add a realm configuration of type `native` to `elasticsearch.yml` under the -`xpack.security.authc.realms` namespace. At a minimum, you must set the realm -`type` to `native`. If you are configuring multiple realms, you should also -explicitly set the `order` attribute. See <> -for all of the options you can set for the `native` realm. -+ -For example, the following snippet shows a `native` realm configuration that -sets the `order` to zero so the realm is checked first: -+ -[source, yaml] ------------------------------------------------------------- -xpack: - security: - authc: - realms: - native1: - type: native - order: 0 ------------------------------------------------------------- - -. Restart Elasticsearch. +See {ref}/[Configuring a Native Realm]. [[native-settings]] ==== Native realm settings diff --git a/x-pack/docs/en/security/configuring-es.asciidoc b/x-pack/docs/en/security/configuring-es.asciidoc index 114fd1cdc4f15..9bcae7fe80d4a 100644 --- a/x-pack/docs/en/security/configuring-es.asciidoc +++ b/x-pack/docs/en/security/configuring-es.asciidoc @@ -73,6 +73,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}. @@ -135,6 +136,7 @@ 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-native-realm.asciidoc[] include::authentication/configuring-pki-realm.asciidoc[] include::{xes-repo-dir}/settings/security-settings.asciidoc[] include::{xes-repo-dir}/settings/audit-settings.asciidoc[] From b9b4e041cb714fde79a8378d71019231ee81f8c5 Mon Sep 17 00:00:00 2001 From: lcawley Date: Mon, 30 Apr 2018 09:14:52 -0700 Subject: [PATCH 2/3] [DOCS] Adds link to native realm settings --- .../authentication/configuring-native-realm.asciidoc | 2 +- .../docs/en/security/authentication/native-realm.asciidoc | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc index 66a86cc75aefa..671f6c26b3317 100644 --- a/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc @@ -21,7 +21,7 @@ the realm chain, temporarily disable the realm, and control its cache options. explicitly set the `order` attribute. + -- -//See <> for all of the options you can set for the `native` realm. +See <> for all of the options you can set for the `native` realm. For example, the following snippet shows a `native` realm configuration that sets the `order` to zero so the realm is checked first: diff --git a/x-pack/docs/en/security/authentication/native-realm.asciidoc b/x-pack/docs/en/security/authentication/native-realm.asciidoc index 486a7725b0c9e..3643e42e02a1c 100644 --- a/x-pack/docs/en/security/authentication/native-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/native-realm.asciidoc @@ -9,12 +9,12 @@ manage user passwords. [float] ==== Configuring a native realm -See {ref}/[Configuring a Native Realm]. +See {ref}/[Configuring a native realm]. [[native-settings]] ==== Native realm settings -See {ref}/security-settings.html#ref-native-settings[Native Realm Settings]. +See {ref}/security-settings.html#ref-native-settings[Native realm settings]. [[managing-native-users]] ==== Managing native users @@ -23,7 +23,7 @@ See {ref}/security-settings.html#ref-native-settings[Native Realm Settings]. *Management / Security / Users* page. Alternatively, you can manage users through the `user` API. For more -information and examples, see {ref}/security-api-users.html[User Management APIs]. +information and examples, see {ref}/security-api-users.html[User management APIs]. [[migrating-from-file]] NOTE: To migrate file-based users to the `native` realm, use the From 55ac50366ab48c4d030bdd1668cb467f12d2ca56 Mon Sep 17 00:00:00 2001 From: lcawley Date: Tue, 1 May 2018 15:20:46 -0700 Subject: [PATCH 3/3] [DOCS] Addressed feedback --- .../authentication/configuring-native-realm.asciidoc | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc index 671f6c26b3317..3c4f44fdfc9d0 100644 --- a/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc @@ -3,12 +3,11 @@ === Configuring a Native Realm The easiest way to manage and authenticate users is with the internal `native` -realm. You don't need to explicitly configure a native realm; it is added to the -realm chain by default. +realm. -IMPORTANT: When you configure realms in `elasticsearch.yml`, only the -realms you specify are used for authentication. To use the -`native` realm as a fallback, you must include it in the realm chain. +The native realm is available by default when no other realms are +configured. If other realm settings have been configured in `elasticsearch.yml`, +you must add the native realm to the realm chain. You can configure options for the `native` realm in the `xpack.security.authc.realms` namespace in `elasticsearch.yml`. Explicitly