From 1a8802668b9a4d4a919c6b53f574b9bdf91ec165 Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Thu, 14 Jul 2022 18:26:01 +1000 Subject: [PATCH 1/4] [DOCS] Separate "user lookup" into its own doc When we introduced "authorization delegation" we piggy backed on the implementation and documentation for "run as". The authorization delegation docs just link to "run as" in order to explain which realms support being the target of delegation. However, authorization delegation is now at least as popular as "run as", and forcing people to make sense of the "run as" docs and apply them to their delegation authorization ("authorization_realm") scenario wasn't helpful or clear. This commit moves (and improves) the content for "lookup a user without authentication" into a new page within the authentication section, and links to it from both "run as" and "delegated authorization". --- .../security/authentication/overview.asciidoc | 1 + .../authentication/realm-chains.asciidoc | 2 +- .../token-authentication-services.asciidoc | 2 + .../authentication/user-lookup.asciidoc | 57 +++++++++++++++++++ ...figuring-authorization-delegation.asciidoc | 4 +- .../authorization/run-as-privilege.asciidoc | 22 +++---- 6 files changed, 75 insertions(+), 13 deletions(-) create mode 100644 x-pack/docs/en/security/authentication/user-lookup.asciidoc diff --git a/x-pack/docs/en/security/authentication/overview.asciidoc b/x-pack/docs/en/security/authentication/overview.asciidoc index 54e1e1dcbad79..96646d30b6ec0 100644 --- a/x-pack/docs/en/security/authentication/overview.asciidoc +++ b/x-pack/docs/en/security/authentication/overview.asciidoc @@ -51,6 +51,7 @@ include::kerberos-realm.asciidoc[] include::jwt-realm.asciidoc[] include::custom-realm.asciidoc[] include::anonymous-access.asciidoc[] +include::user-lookup.asciidoc[] include::user-cache.asciidoc[] include::saml-guide.asciidoc[leveloffset=+1] include::oidc-guide.asciidoc[leveloffset=+1] diff --git a/x-pack/docs/en/security/authentication/realm-chains.asciidoc b/x-pack/docs/en/security/authentication/realm-chains.asciidoc index 08da78b14442a..0a9370f2589c2 100644 --- a/x-pack/docs/en/security/authentication/realm-chains.asciidoc +++ b/x-pack/docs/en/security/authentication/realm-chains.asciidoc @@ -78,7 +78,7 @@ LDAP group assignments to determine their roles in Elasticsearch. Any realm that supports retrieving users (without needing their credentials) can be used as an _authorization realm_ (that is, its name may appear as one of the -values in the list of `authorization_realms`). See <> for +values in the list of `authorization_realms`). See <> for further explanation on which realms support this. For realms that support this feature, it can be enabled by configuring the diff --git a/x-pack/docs/en/security/authentication/token-authentication-services.asciidoc b/x-pack/docs/en/security/authentication/token-authentication-services.asciidoc index f7cab7e48344d..8e49ab678f087 100644 --- a/x-pack/docs/en/security/authentication/token-authentication-services.asciidoc +++ b/x-pack/docs/en/security/authentication/token-authentication-services.asciidoc @@ -33,6 +33,7 @@ curl -H "Authorization: Bearer AAEAAWVsYXN0aWMvZ...mXQtc2VydmMTpyNXdkYmRib1FTZTl include::service-accounts.asciidoc[tag=service-accounts-usage] -- +[[token-authentication-access-token]] _token-service_:: The token service uses the <> to generate access tokens and refresh tokens based on the OAuth2 specification. @@ -51,6 +52,7 @@ curl -H "Authorization: Bearer dGhpcyBpcyBub3Qx5...F0YS4gZG8gbm90IHRyeSB0byByZWF // NOTCONSOLE -- +[[token-authentication-api-key]] _api-key-service_:: The API key service uses the <> to generate API keys. diff --git a/x-pack/docs/en/security/authentication/user-lookup.asciidoc b/x-pack/docs/en/security/authentication/user-lookup.asciidoc new file mode 100644 index 0000000000000..522e6da88b5ac --- /dev/null +++ b/x-pack/docs/en/security/authentication/user-lookup.asciidoc @@ -0,0 +1,57 @@ +[role="xpack"] +[[user-lookup]] +=== Looking up users without authentication + +{es} <> exist primarily to support +<>. +Some realms authenticate users via a password (for example the +<> and <> realms) and other realms use +more complex authentication protocols (for example the <> and +<> realms). +In each case, the _primary_ purpose of the realm is to establish the identity of +the user who has made a request to the {es} API. + +However, some {es} features need to _lookup_ a user without using their credentials. + +- The <> feature executes requests on behalf of + another user. An authenticated user with `run_as` privileges can perform + requests on behalf of another unauthenticated user. + +- The <> feature links two realms + together so that a user who authenticates against one realm can have the roles + and metadata associated with a user from a different realm. + +In each of the above cases the second user must be resolved without directly +authenticating. The ability for a realm to lookup a user by username is an +optional operation that is not supported by all realms. + +The reserved, <> and <> realms always +support user lookup. + +The <> realm supports user lookup when the realm is configured +in <>. User lookup is not support +when the realm is configured with `user_dn_templates`. + +User lookup support in the <> realm +requires that the realm be configured with a <> and a +bind password. + +The `pki`, `saml`, `oidc`, `kerberos` and `jwt` realms do not support user +lookup. + +NOTE: If you want to use a realm for _user lookup_ only, and prevent users from + authenticating against that realm, you can + <> and set + `authentication.enabled` to `false` + +The user lookup feature is an internal capability that is used to implement the +`run-as` and delegated authorization features - there are no APIs for user lookup. +If you wish to test your user lookup configuration, then you can do this with +`run_as`. Use the <> API, authenticate as a +`superuser` (e.g. the builtin `elastic` user) and specify the +<>. + +NOTE: The <> API and <> feature are alternative + ways to retrieve information about a {stack} user. Those APIs are not related + to the user lookup feature. + diff --git a/x-pack/docs/en/security/authorization/configuring-authorization-delegation.asciidoc b/x-pack/docs/en/security/authorization/configuring-authorization-delegation.asciidoc index eda2800dceb1b..f2a54ff4077e9 100644 --- a/x-pack/docs/en/security/authorization/configuring-authorization-delegation.asciidoc +++ b/x-pack/docs/en/security/authorization/configuring-authorization-delegation.asciidoc @@ -4,8 +4,8 @@ In some cases, after the user has been authenticated by a realm, we may want to delegate user lookup and assignment of roles to another realm. -Any realm that supports retrieving users (without needing their credentials) -can be used as an authorization realm. +Any realm that supports <> (without needing the +the user's credentials) can be used as an authorization realm. For example, a user that is authenticated by the Kerberos realm can be looked up in the LDAP realm. The LDAP realm takes on responsibility for searching the user diff --git a/x-pack/docs/en/security/authorization/run-as-privilege.asciidoc b/x-pack/docs/en/security/authorization/run-as-privilege.asciidoc index 5a9fbecf92ab0..928ffa4d68679 100644 --- a/x-pack/docs/en/security/authorization/run-as-privilege.asciidoc +++ b/x-pack/docs/en/security/authorization/run-as-privilege.asciidoc @@ -30,15 +30,17 @@ support `run_as` delegation. `run_as` user:: -- -For the `run_as` user, the the following realms support delegated -`run_as` lookups by username: `native`, `file`, Active Directory, LDAP. - -NOTE: To support `run_as` in the LDAP realm, you have to run in -<>. For Active Directory, you need -to <>. - -Service tokens, the {es} Token Service, PKI, SAML 2.0, OIDC 1.0, Kerberos, JWT, -and API keys do not support delegated `run_as` lookups. +{es} supports `run_as` for any user that can be retrieved via +<>. +Not all realms support user lookup - please check the list of supported realms +and ensure that the realm you wish to use is configured in a manner that +supports user lookup. + +The `run_as` user must be retrieved from a <> - it is not +possible to run as a +<>, +<> or +<>. -- To submit requests on behalf of other users, you need to have the `run_as` @@ -216,4 +218,4 @@ The `authentication_realm` and `lookup_realm` in the response both specify the `native` realm because both the `admin_user` and `analyst_user` are from that realm. If the two users are in different realms, the values for `authentication_realm` and `lookup_realm` are different (such as `pki` and -`native`). \ No newline at end of file +`native`). From 086fb4282807dd29dd36dee0e7c1dbd4d56c1c70 Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Thu, 14 Jul 2022 18:33:24 +1000 Subject: [PATCH 2/4] Remove duplicated "the" --- .../authorization/configuring-authorization-delegation.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/authorization/configuring-authorization-delegation.asciidoc b/x-pack/docs/en/security/authorization/configuring-authorization-delegation.asciidoc index f2a54ff4077e9..11c3f86613500 100644 --- a/x-pack/docs/en/security/authorization/configuring-authorization-delegation.asciidoc +++ b/x-pack/docs/en/security/authorization/configuring-authorization-delegation.asciidoc @@ -5,7 +5,7 @@ In some cases, after the user has been authenticated by a realm, we may want to delegate user lookup and assignment of roles to another realm. Any realm that supports <> (without needing the -the user's credentials) can be used as an authorization realm. +user's credentials) can be used as an authorization realm. For example, a user that is authenticated by the Kerberos realm can be looked up in the LDAP realm. The LDAP realm takes on responsibility for searching the user From cb61ec98dd0372c8ec188880f011df35c14f0138 Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Wed, 27 Jul 2022 15:52:19 +1000 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Adam Locke --- .../authentication/user-lookup.asciidoc | 23 ++++++++----------- .../authorization/run-as-privilege.asciidoc | 5 ++-- 2 files changed, 12 insertions(+), 16 deletions(-) diff --git a/x-pack/docs/en/security/authentication/user-lookup.asciidoc b/x-pack/docs/en/security/authentication/user-lookup.asciidoc index 522e6da88b5ac..7e1cea09a153b 100644 --- a/x-pack/docs/en/security/authentication/user-lookup.asciidoc +++ b/x-pack/docs/en/security/authentication/user-lookup.asciidoc @@ -4,14 +4,14 @@ {es} <> exist primarily to support <>. -Some realms authenticate users via a password (for example the -<> and <> realms) and other realms use -more complex authentication protocols (for example the <> and +Some realms authenticate users with a password (such as the +<> and <> realms), and other realms use +more complex authentication protocols (such as the <> and <> realms). In each case, the _primary_ purpose of the realm is to establish the identity of the user who has made a request to the {es} API. -However, some {es} features need to _lookup_ a user without using their credentials. +However, some {es} features need to _look up_ a user without using their credentials. - The <> feature executes requests on behalf of another user. An authenticated user with `run_as` privileges can perform @@ -25,24 +25,21 @@ In each of the above cases the second user must be resolved without directly authenticating. The ability for a realm to lookup a user by username is an optional operation that is not supported by all realms. -The reserved, <> and <> realms always +* The reserved, <> and <> realms always support user lookup. - -The <> realm supports user lookup when the realm is configured +* The <> realm supports user lookup when the realm is configured in <>. User lookup is not support when the realm is configured with `user_dn_templates`. - -User lookup support in the <> realm +* User lookup support in the <> realm requires that the realm be configured with a <> and a bind password. The `pki`, `saml`, `oidc`, `kerberos` and `jwt` realms do not support user lookup. -NOTE: If you want to use a realm for _user lookup_ only, and prevent users from - authenticating against that realm, you can - <> and set - `authentication.enabled` to `false` +NOTE: If you want to use a realm only for user lookup and prevent users from +authenticating against that realm, you can <> +and set `authentication.enabled` to `false` The user lookup feature is an internal capability that is used to implement the `run-as` and delegated authorization features - there are no APIs for user lookup. diff --git a/x-pack/docs/en/security/authorization/run-as-privilege.asciidoc b/x-pack/docs/en/security/authorization/run-as-privilege.asciidoc index 928ffa4d68679..093a8814d8f02 100644 --- a/x-pack/docs/en/security/authorization/run-as-privilege.asciidoc +++ b/x-pack/docs/en/security/authorization/run-as-privilege.asciidoc @@ -30,9 +30,8 @@ support `run_as` delegation. `run_as` user:: -- -{es} supports `run_as` for any user that can be retrieved via -<>. -Not all realms support user lookup - please check the list of supported realms +{es} supports `run_as` for any realm that supports user lookup. +Not all realms support user lookup. Refer to the list of <> and ensure that the realm you wish to use is configured in a manner that supports user lookup. From e7ccb2580d3eea36808c085177f7e96da2f8d7ac Mon Sep 17 00:00:00 2001 From: Tim Vernum Date: Wed, 10 Aug 2022 15:30:29 +1000 Subject: [PATCH 4/4] Attempt to clarify examples --- .../authentication/user-lookup.asciidoc | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/x-pack/docs/en/security/authentication/user-lookup.asciidoc b/x-pack/docs/en/security/authentication/user-lookup.asciidoc index 7e1cea09a153b..179abd2de1e5c 100644 --- a/x-pack/docs/en/security/authentication/user-lookup.asciidoc +++ b/x-pack/docs/en/security/authentication/user-lookup.asciidoc @@ -21,9 +21,21 @@ However, some {es} features need to _look up_ a user without using their credent together so that a user who authenticates against one realm can have the roles and metadata associated with a user from a different realm. -In each of the above cases the second user must be resolved without directly -authenticating. The ability for a realm to lookup a user by username is an -optional operation that is not supported by all realms. +In each of these cases, a user must first authenticate to one realm and then +{es} will query the second realm to find another user. +The authenticated user credentials are used to authenticate in the first realm only, +The user in the second realm is retrieved by username, without needing credentials. + +When {es} resolves a user using their credentials (as performed in the first realm), +it is known as _user authentication_. + +When {es} resolves a user using the username only (as performed in the second realm), +it is known as _user lookup_. + +See the <> and <> +documentation to learn more about these features, including which realms and authentication +methods support `run_as` or delegated authorization. +In both cases, only the following realms can be used for the user lookup: * The reserved, <> and <> realms always support user lookup.