Authentication in X-Pack security is handled by one or more authentication services called realms. A realm is used to resolve and authenticate users based on authentication tokens. X-Pack security provides the following built-in realms:

X-Pack security also supports custom realms. If you need to integrate with another authentication system, you can build a custom realm plugin. For more information, see Integrating with Other Authentication Systems.

Realms 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, X-Pack security 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.

Realm types can roughly be classified in two categories: