WARNING: Version 5.5 of the Elastic Stack has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
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:
- An internal realm where users are stored in a dedicated Elasticsearch index. This realm supports an authentication token in the form of username and password, and is available by default when no realms are explicitly configured. See Native User Authentication.
- A realm that uses an external LDAP server to authenticate the users. This realm supports an authentication token in the form of username and password, and requires explicit configuration in order to be used. See LDAP User Authentication.
- A realm that uses an external Active Directory Server to authenticate the users. With this realm, users are authenticated by usernames and passwords. See Active Directory User Authentication.
- A realm that authenticates users using Public Key Infrastructure (PKI). This realm works in conjunction with SSL/TLS and identifies the users through the Distinguished Name (DN) of the client’s X.509 certificates. See PKI User Authentication.
- An internal realm where users are defined in files stored on each node in the Elasticsearch cluster. This realm supports an authentication token in the form of username and password, and is always available. See File-based User Authentication.
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. 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
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
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
file realms, you must include them in the chain.
The following snippet configures a realm chain that includes the
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 three settings that are common to all realms:
Identifies the type of the realm. The realm type
determines what other settings the realms should be
configured with. The type can be one of:
A numeric value representing the priority/index of the realm within the realm chain. This will determine the order by which the realms will be consulted during authentication, with lower order being consulted first.
When set to
Realm types can roughly be classified in two categories:
- Realms that are internal to Elasticsearch and don’t require any
communication with external parties. They are fully managed by
X-Pack security. There can only be a maximum of one configured realm
per internal realm type. X-Pack security provides two internal realm
- Realms that require interaction with parties/components external to
Elasticsearch, typically, with enterprise grade identity management
systems. Unlike internal realms, there can be as many external realms
as one would like - each with its own unique name and configuration.
X-Pack security provides three external realm types: