105 lines
4.2 KiB
Plaintext
105 lines
4.2 KiB
Plaintext
|
[role="xpack"]
|
||
|
|
[[realm-chains]]
|
||
|
|
=== Realm chains
|
||
|
|
|
||
|
|
<<realms,Realms>> live within a _realm chain_. It is essentially a prioritized
|
||
|
|
list of configured realms (typically of various types). Realms are consulted in
|
||
|
|
ascending order (that is to say, the realm with the lowest `order` value is
|
||
|
|
consulted first). You should make sure each configured realm has a distinct
|
||
|
|
`order` setting. In the event that two or more realms have the same `order`,
|
||
|
|
they are processed in `name` order.
|
||
|
|
|
||
|
|
During the authentication process, {stack} {security-features} consult and try
|
||
|
|
to authenticate the request one realm at a time. Once one of the realms
|
||
|
|
successfully authenticates the request, the authentication is considered to be
|
||
|
|
successful. The authenticated user is associated with the request, which then
|
||
|
|
proceeds to the authorization phase. If a realm cannot authenticate the request,
|
||
|
|
the next realm in the chain is consulted. If all realms in the chain cannot
|
||
|
|
authenticate the request, the authentication is considered to be unsuccessful
|
||
|
|
and an authentication error is returned (as HTTP status code `401`).
|
||
|
|
|
||
|
|
NOTE: Some systems (e.g. Active Directory) have a temporary lock-out period
|
||
|
|
after several successive failed login attempts. If the same username exists in
|
||
|
|
multiple realms, unintentional account lockouts are possible. For more
|
||
|
|
information, see <<trouble-shoot-active-directory>>.
|
||
|
|
|
||
|
|
The default realm chain contains the `native` and `file` realms. To explicitly
|
||
|
|
configure a realm chain, you specify the chain in the `elasticsearch.yml` file.
|
||
|
|
When you configure a realm chain, only the realms you specify are used for
|
||
|
|
authentication. To use the `native` and `file` realms, you must include them in
|
||
|
|
the chain.
|
||
|
|
|
||
|
|
The following snippet configures a realm chain that includes the `file` and
|
||
|
|
`native` realms, as well as two LDAP realms and an Active Directory realm.
|
||
|
|
|
||
|
|
[source,yaml]
|
||
|
|
----------------------------------------
|
||
|
|
xpack.security.authc:
|
||
|
|
realms:
|
||
|
|
|
||
|
|
file:
|
||
|
|
type: file
|
||
|
|
order: 0
|
||
|
|
|
||
|
|
native:
|
||
|
|
type: native
|
||
|
|
order: 1
|
||
|
|
|
||
|
|
ldap1:
|
||
|
|
type: ldap
|
||
|
|
order: 2
|
||
|
|
enabled: false
|
||
|
|
url: 'url_to_ldap1'
|
||
|
|
...
|
||
|
|
|
||
|
|
ldap2:
|
||
|
|
type: ldap
|
||
|
|
order: 3
|
||
|
|
url: 'url_to_ldap2'
|
||
|
|
...
|
||
|
|
|
||
|
|
ad1:
|
||
|
|
type: active_directory
|
||
|
|
order: 4
|
||
|
|
url: 'url_to_ad'
|
||
|
|
----------------------------------------
|
||
|
|
|
||
|
|
As can be seen above, each realm has a unique name that identifies it. Each type
|
||
|
|
of realm dictates its own set of required and optional settings. That said,
|
||
|
|
there are
|
||
|
|
{ref}/security-settings.html#ref-realm-settings[settings that are common to all realms].
|
||
|
|
|
||
|
|
[[authorization_realms]]
|
||
|
|
==== Delegating authorization to another realm
|
||
|
|
|
||
|
|
Some realms have the ability to perform _authentication_ internally, but
|
||
|
|
delegate the lookup and assignment of roles (that is, _authorization_) to
|
||
|
|
another realm.
|
||
|
|
|
||
|
|
For example, you may wish to use a PKI realm to authenticate your users with
|
||
|
|
TLS client certificates, then lookup that user in an LDAP realm and use their
|
||
|
|
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
|
||
|
|
further explanation on which realms support this.
|
||
|
|
|
||
|
|
For realms that support this feature, it can be enabled by configuring the
|
||
|
|
`authorization_realms` setting on the authenticating realm. Check the list of
|
||
|
|
{ref}/security-settings.html#realm-settings[supported settings] for each realm
|
||
|
|
to see if they support the `authorization_realms` setting.
|
||
|
|
|
||
|
|
If delegated authorization is enabled for a realm, it authenticates the user in
|
||
|
|
its standard manner (including relevant caching) then looks for that user in the
|
||
|
|
configured list of authorization realms. It tries each realm in the order they
|
||
|
|
are specified in the `authorization_realms` setting. The user is retrieved by
|
||
|
|
principal - the user must have identical usernames in the _authentication_ and
|
||
|
|
_authorization realms_. If the user cannot be found in any of the authorization
|
||
|
|
realms, authentication fails.
|
||
|
|
|
||
|
|
See <<configuring-authorization-delegation>> for more details.
|
||
|
|
|
||
|
|
NOTE: Delegated authorization requires a
|
||
|
|
https://www.elastic.co/subscriptions[Platinum or Trial license].
|