Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 6 commits into from
Aug 12, 2022
Merged

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

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1a88026
[DOCS] Separate "user lookup" into its own doc
tvernum Jul 14, 2022
086fb42
Remove duplicated "the"
tvernum Jul 14, 2022
cb61ec9
Apply suggestions from code review
tvernum Jul 27, 2022
813da5b
Merge branch 'main' into docs/user-lookup
elasticmachine Aug 10, 2022
e7ccb25
Attempt to clarify examples
tvernum Aug 10, 2022
2da18a6
Merge branch 'main' into docs/user-lookup
elasticmachine Aug 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions x-pack/docs/en/security/authentication/overview.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
2 changes: 1 addition & 1 deletion x-pack/docs/en/security/authentication/realm-chains.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions x-pack/docs/en/security/authentication/token-authentication-services.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down
54 changes: 54 additions & 0 deletions x-pack/docs/en/security/authentication/user-lookup.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
[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 the above cases the second user must be resolved without directly
jakelandis marked this conversation as resolved.
Show resolved Hide resolved
authenticating. The ability for a realm to lookup a user by username is an
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

optional operation that is not supported by all realms.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@justincr-elastic justincr-elastic Aug 8, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


* 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

4 changes: 2 additions & 2 deletions ...ck/docs/en/security/authorization/configuring-authorization-delegation.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 11 additions & 10 deletions x-pack/docs/en/security/authorization/run-as-privilege.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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`).