NOTE: You are looking at documentation for an older release. For the latest information, see the current release documentation.
Realm chains
editRealm chains
editRealms live within a realm chain. It is essentially a prioritized list of
configured realms (typically of various types). The order of the list determines
the order in which the realms will be consulted. 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 will be processed in name order.
During the authentication process, Elastic Stack security features will 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 and the authenticated user will be associated
with the request (which will then proceed to the authorization phase). If a realm
cannot authenticate the request, the next in line realm in the chain will be
consulted. If all realms in the chain could not authenticate the request, the
authentication is then considered to be unsuccessful and an authentication error
will be returned (as HTTP status code 401).
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, please see here.
The default realm chain contains the native and file realms. To explicitly,
configure a realm chain, you specify the chain in elasticsearch.yml. 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.
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 and each realm type dictates its own set of required and optional settings. That said, there are settings that are common to all realms.
Delegating authorization to another realm
editSome 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, but 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 Submitting requests on behalf of other users 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
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.
Delegated authorization requires a Platinum or Trial license.