[DOCS] Separate "user lookup" into its own doc (elastic#88533)

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".

Co-authored-by: Adam Locke <[email protected]>

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]

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 <<run-as-privilege>> for
+values in the list of `authorization_realms`). See <<user-lookup>> for
 further explanation on which realms support this.
 
 For realms that support this feature, it can be enabled by configuring the

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 <<security-api-get-token,get token API>> 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
 <<security-api-create-api-key,create API key API>> to generate API keys.

x-pack/docs/en/security/authentication/user-lookup.asciidoc

@@ -0,0 +1,66 @@
+[role="xpack"]
+[[user-lookup]]
+=== Looking up users without authentication
+
+{es} <<realms,realms>> exist primarily to support
+<<setting-up-authentication,user authentication>>. 
+Some realms authenticate users with a password (such as the
+<<native-realm,`native`>> and <<ldap-realm,`ldap`>> realms), and other realms use
+more complex authentication protocols (such as the <<saml-realm,`saml`>> and
+<<oidc-realm,`oidc`>> 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 _look up_ a user without using their credentials.
+
+- The <<run-as-privilege,`run_as`>> 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 <<authorization_realms,delegated authorization>> 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 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 <<run-as-privilege,run_as>> and <<authorization_realms,delegated authorization>>
+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, <<native-realm,`native`>> and <<file-realm,`file`>> realms always 
+support user lookup.
+* The <<ldap-realm,`ldap`>> realm supports user lookup when the realm is configured
+in <<ldap-realm-configuration,_user search_ mode>>. User lookup is not support
+when the realm is configured with `user_dn_templates`.
+* User lookup support in the <<active-directory-realm,`active_directory`>> realm
+requires that the realm be configured with a <<ref-ad-settings,`bind_dn`>> 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 only for user lookup and prevent users from 
+authenticating against that realm, you can <<ref-realm-settings,configure the realm>>
+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 <<security-api-authenticate>> API, authenticate as a
+`superuser` (e.g. the builtin `elastic` user) and specify the
+<<run-as-privilege, `es-security-runas-user` request header>>.
+
+NOTE: The <<security-api-get-user>> API and <<user-profile>> feature are alternative
+      ways to retrieve information about a {stack} user. Those APIs are not related
+      to the user lookup feature.
+

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 <<user-lookup,user lookup>> (without needing 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

x-pack/docs/en/security/authorization/run-as-privilege.asciidoc

@@ -30,15 +30,16 @@ 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
-<<ldap-realm-configuration,_user search_ mode>>. For Active Directory, you need
-to <<ref-ad-settings,configure a `bind_dn` and `secure_bind_password`>>.
-
-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 realm that supports user lookup.
+Not all realms support user lookup. Refer to the list of <<user-lookup,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 <<realms,realm>> - it is not
+possible to run as a
+<<service-accounts,service account>>,
+<<token-authentication-api-key,API key>> or 
+<<token-authentication-access-token,access token>>.
 --
 
 To submit requests on behalf of other users, you need to have the `run_as`
@@ -216,4 +217,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`).
+`native`).