[DOCS] Separate "user lookup" into its own doc

[tvernum]

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

Preview link: https://elasticsearch_88533.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/user-lookup.html

[elasticmachine]

Pinging @elastic/es-docs (Team:Docs)

[elasticmachine]

Pinging @elastic/es-security (Team:Security)

[jakelandis]

should we be de-emphasizing the built in 'elastic' user as well as the super user role ?

[tvernum]

I don't think so. It's the only user we ship with that is able to be used for this sort of testing, so I don't think there's any reason so avoid suggesting it as an option here.

[jakelandis]

changes look good ! I think this is very helpful. ++ as-is , but with minor wording suggestion

[lockewritesdocs]

Added some minor suggestions for edits, but looks solid overall. Thanks for adding this page @tvernum!

[lockewritesdocs]

Suggested change

	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. Authorization is handled by looking up that user in a second realm. The user is authenticated in the first realm, but only must exist in the second realm (the user doesn't need credentials to the second realm). Querying the second realm for authorization purposes is known as user lookup.
	See the <<run-as-privilege,run_as>> and <<authorization_realms,delegated authorization>> documentation for which realms support the ability to perform `run_as` or delegate authorization. In both cases, only the following realms can be used for the user lookup:

[lockewritesdocs]

I like Jake's suggestion, so I added it as a suggested change with minor edits.

[jakelandis]

Thanks Adam ... i really need to figure out how to do multi-line suggestions in GH (and edits look good)

[tvernum]

I think the phrasing around "Authorization" is slightly misleading for run-as.

Authorization is performed for the first user to ensure they are permitted to "run as" the second user, and then authorization checks are performed again to ensure the 2nd user is permitted to execute the request.
The proposed wording implies that authorization is exclusive performed against the second user.

I'll try and come up with a variation that avoid that implication.

[lockewritesdocs]

@tvernum, here's a suggested version that incorporates the distinction you highlighted:

In both cases, a user must authenticate to a realm first. After successfully authenticating, two authorization
checks occur:

• The first check ensures that the authenticated user has privileges to execute requests as a different user.
• The second check ensures that the unauthenticated user (the second user) has privileges to execute the
  specified request.

Querying the second realm to retrieve the unauthenticated user's privileges is known as a user lookup. The authenticated user doesn't need credentials in the second realm; they only need to exist in that realm.

[justincr-elastic]

I think describing it in order of operations helps to understand the relationship of delegated authz vs run-as.

If a realm successfully authenticates a user, a realm can be configured to choose the authenticated user's privileges by one of these two configured options. The options cannot be used simultaneously.

1. The realm that performed authentication can do the authorization lookups.
2. The realm that performed authentication can list a subset of other realms to do the authorization lookups by username.

After the authenticated user has been authorized by one of the above configured methods, one more check is done before servicing a request.

If the request includes a run-as header, the authenticated user's privileges are checked to see if it is allowed to run-as that requests user. If yes, all configured realms are asked to do a lookup of the run-as user by username. If the run-as user is found, the first realm to find that username returns that run-as user with a set of privileges resolved by that lookup realm. The request is then executed as the run-as user, with the run-as user's privileges, not the original authenticated user's privileges.

All 10 realms can request delegated authorization: reserved, native, file, ldap, ad, pki, saml, oidc, kerberos, jwt.

Only 4 realms can fulfill delegated authorizations: native, file, ldap, ad

There is overlap where an LDAP/AD realm can authenticate, and then request delegated authorization from a different LDAP/AD realm. Note, recursion does not make sense; an LDAP/AD realm should not delegate authorization to itself, just omit the delegated authorization setting.

[tvernum]

This is a doc trying to describe user lookup, not run as or delegated authorization. Both those features have their own docs, I don't want to explain them again here.

The point of mentioning them is to provide examples of why the concept of user lookup exists so that the description has some context, but if the readers want to know more details about run-as or delegated authorization they should read the pages for those 2 features.

I'm happy to make this paragraph clearer, but I don't want to end up becoming a distraction from the purpose of the page.

[lockewritesdocs]

Added a suggestion for distinguishing the two authorization checks that occur with run_as and delegated authorization.

[lockewritesdocs]

Suggested change

	authenticating. The ability for a realm to lookup a user by username is an
	authenticating. The ability for a realm to look up a user by username is an

[lockewritesdocs]

@tvernum, here's a suggested version that incorporates the distinction you highlighted:

In both cases, a user must authenticate to a realm first. After successfully authenticating, two authorization
checks occur:

• The first check ensures that the authenticated user has privileges to execute requests as a different user.
• The second check ensures that the unauthenticated user (the second user) has privileges to execute the
  specified request.

Querying the second realm to retrieve the unauthenticated user's privileges is known as a user lookup. The authenticated user doesn't need credentials in the second realm; they only need to exist in that realm.

[justincr-elastic]

LGTM

[tvernum]

@elasticmachine update branch

[tvernum]

@elasticmachine update branch

[elasticsearchmachine]

💚 Backport successful

Status	Branch	Result
✅	8.3
✅	8.4