OpenSearch/x-pack/docs/en/security/authentication/realm-chains.asciidoc

[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.file1:
      order: 0

  native.native1:
      order: 1

  ldap.ldap1:
      order: 2
      enabled: false
      url: 'url_to_ldap1'
      ...

  ldap.ldap2:
      order: 3
      url: 'url_to_ldap2'
      ...

  active_directory.ad1:
      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].