[[ldap-realm]]
===  LDAP User Authentication

You can configure {security} to communicate with a Lightweight Directory Access
Protocol (LDAP) server to authenticate users. To integrate with LDAP, you
configure an `ldap` realm and map LDAP groups to user roles in the
<<mapping-roles, role mapping file>>.

To protect passwords, communications between Elasticsearch and the LDAP server
should be encrypted using SSL/TLS. Clients and nodes that connect via SSL/TLS to
the LDAP server need to have the LDAP server's certificate or the server's root
CA certificate installed in their _keystore_ or _truststore_. For more information
about installing certificates, see <<ldap-ssl>>.

==== Configuring an LDAP Realm

LDAP stores users and groups hierarchically, similar to the way folders are
grouped in a file system. An LDAP directory's hierarchy is built from containers
such as the _organizational unit_ (`ou`), _organization_ (`o`), and
_domain controller_ (`dc`).

The path to an entry is a _Distinguished Name_ (DN) that uniquely identifies a
user or group. User and group names typically have attributes such as a
_common name_ (`cn`) or _unique ID_ (`uid`). A DN is specified as a string,
for example  `"cn=admin,dc=example,dc=com"` (white spaces are ignored).

The `ldap` realm supports two modes of operation, a user search mode
and a mode with specific templates for user DNs. See
<<ldap-settings, LDAP Realm Settings>> for all of the options you can set for an
`ldap` realm.

[[ldap-user-search]]
===== User Search Mode
LDAP user search is the most common mode of operation. In this mode, a specific
user with permission to search the LDAP directory is used to search for the
authenticating user DN based on its username and an LDAP attribute. Once found,
the user will be authenticated by attempting to bind to the LDAP server using the
found DN and the provided password.

To configure an `ldap` Realm with User Search:

. Add a realm configuration of type `ldap` to `elasticsearch.yml` under the
`xpack.security.authc.realms` namespace. At a minimum, you must set the realm `type`
to `ldap`, specify the `url` of the LDAP server, and set `user_search.base_dn`
to the container DN where the users are searched for. If you are configuring
multiple realms, you should also explicitly set the `order` attribute to control
the order in which the realms are consulted during authentication. See
<<ldap-settings, LDAP Realm Settings>> for all of the options you can set for an
`ldap` realm.
+
For example, the following snippet shows an LDAP realm configured with a user search:
+
[source, yaml]
------------------------------------------------------------
xpack:
  security:
    authc:
      realms:
        ldap1:
          type: ldap
          order: 0
          url: "ldaps://ldap.example.com:636"
          bind_dn: "cn=ldapuser, ou=users, o=services, dc=example, dc=com"
          bind_password: changeme
          user_search:
            base_dn: "dc=example,dc=com"
            attribute: cn
          group_search:
            base_dn: "dc=example,dc=com"
          files:
            role_mapping: "CONFIG_DIR/x-pack/role_mapping.yml"
          unmapped_groups_as_roles: false
------------------------------------------------------------
+
IMPORTANT: When you configure realms in `elasticsearch.yml`, only the 
realms you specify are used for authentication. If you also want to use the 
`native` or `file` realms, you must include them in the realm chain. 

. Restart Elasticsearch


===== User DN Templates Mode
If your LDAP environment uses a few specific standard naming conditions for
users, you can use User DN templates to configure the realm. The advantage of
this method is that a search does not have to be performed to find the user DN.
However, multiple bind operations might be needed to find the correct user DN.

To configure an `ldap` Realm with User Search:

. Add a realm configuration of type `ldap` to `elasticsearch.yml` in the
`xpack.security.authc.realms` namespace. At a minimum, you must set the realm `type` to
`ldap`, specify the `url` of the LDAP server, and specify at least one template
with the `user_dn_templates` option. If you are configuring multiple realms, you
should also explicitly set the `order` attribute to control the order in which
the realms are consulted during authentication. See <<ldap-settings, LDAP Realm Settings>>
for all of the options you can set for an `ldap` realm.
+
For example, the following snippet shows an LDAP realm configured with User DN templates:
+
[source, yaml]
------------------------------------------------------------
xpack:
  security:
    authc:
      realms:
        ldap1:
          type: ldap
          order: 0
          url: "ldaps://ldap.example.com:636"
          user_dn_templates:
            - "cn={0}, ou=users, o=marketing, dc=example, dc=com"
            - "cn={0}, ou=users, o=engineering, dc=example, dc=com"
          group_search:
            base_dn: "dc=example,dc=com"
          files:
            role_mapping: "/mnt/elasticsearch/group_to_role_mapping.yml"
          unmapped_groups_as_roles: false
------------------------------------------------------------

. Restart Elasticsearch


[[ldap-load-balancing]]
===== Load Balancing and Failover
The `load_balance.type` setting can be used at the realm level to configure how
{security} should interact with multiple LDAP servers. {security} supports both
failover and load balancing modes of operation.

.Load Balancing and Failover Types
|=======================
| Type              | | | Description
| `failover`        | | | The URLs specified are used in the order that they are specified.
                          The first server that can be connected to will be used for all
                          subsequent connections. If a connection to that server fails then
                          the next server that a connection can be established to will be
                          used for subsequent connections.
| `dns_failover`    | | | In this mode of operation, only a single URL may be specified.
                          This URL must contain a DNS name. The system will be queried for
                          all IP addresses that correspond to this DNS name. Connections to
                          the LDAP server will always be tried in the order in which they
                          were retrieved. This differs from `failover` in that there is no
                          reordering of the list and if a server has failed at the beginning
                          of the list, it will still be tried for each subsequent connection.
| `round_robin`     | | | Connections will continuously iterate through the list of provided
                          URLs. If a server is unavailable, iterating through the list of
                          URLs will continue until a successful connection is made.
| `dns_round_robin` | | | In this mode of operation, only a single URL may be specified. This
                          URL must contain a DNS name. The system will be queried for all IP
                          addresses that correspond to this DNS name. Connections will
                          continuously iterate through the list of addresses. If a server is
                          unavailable, iterating through the list of URLs will continue until
                          a successful connection is made.
|=======================


[[ldap-settings]]
===== LDAP Realm Settings

.Common LDAP Realm Settings
[cols="4,^3,10"]
|=======================
| Setting                        | Required | Description
| `type`                         | yes      | Indicates the realm type. Must be set to `ldap`.
| `order`                        | no       | Indicates the priority of this realm within the realm
                                              chain. Realms with a lower order are consulted first.
                                              Although not required, we recommend explicitly
                                              setting this value when you configure multiple realms.
                                              Defaults to `Integer.MAX_VALUE`.
| `enabled`                      | no       | Indicates whether this realm is enabled or disabled.
                                              Enables you to disable a realm without removing its
                                              configuration. Defaults to `true`.
| `url`                          | yes      | Specifies one or more LDAP URLs of the form of
                                              `ldap[s]://<server>:<port>`. Multiple URLs can be
                                              defined using a comma separated value or array syntax:
                                              `[ "ldaps://server1:636", "ldaps://server2:636" ]`.
                                              `ldaps` and `ldap` URL protocols cannot be mixed in
                                              the same realm.
| `load_balance.type`            | no       | The behavior to use when there are multiple LDAP URLs
                                              defined. For supported values see
                                              <<ldap-load-balancing, LDAP load balancing and failover types>>.
| `load_balance.cache_ttl`       | no       | When using `dns_failover` or `dns_round_robin` as the
                                              load balancing type, this setting controls the amount of time
                                              to cache DNS lookups. Defaults to `1h`.
| `user_group_attribute`         | no       | Specifies the attribute to examine on the user for group
                                              membership. The default is `memberOf`. This setting will
                                              be ignored if any `group_search` settings are specified.
| `group_search.base_dn`         | no       | Specifies a container DN to search for groups in which
                                              the user has membership. When this element is absent,
                                              Security searches for the attribute specified by
                                              `user_group_attribute` set on the user to determine
                                              group membership.
| `group_search.scope`           | no       | Specifies whether the group search should be
                                              `sub_tree`, `one_level` or `base`.  `one_level` only
                                              searches objects directly contained within the
                                              `base_dn`. The default `sub_tree` searches all objects
                                              contained under `base_dn`. `base` specifies that the
                                              `base_dn` is a group object, and that it is the only
                                              group considered.
| `group_search.filter`          | no       | Specifies a filter to use to lookup a group. If not
                                              set, the realm searches for `group`,
                                              `groupOfNames`, `groupOfUniqueNames`, or `posixGroup` with the
                                              attributes `member`, `memberOf`, or `memberUid`. Any instance of
                                              `{0}` in the filter is replaced by the user
                                              attribute defined in `group_search.user_attribute`
| `group_search.user_attribute`  | no       | Specifies the user attribute that is fetched and
                                              provided as a parameter to the filter.  If not set,
                                              the user DN is passed to the filter.
| `unmapped_groups_as_roles`     | no       | Specifies whether the names of any unmapped LDAP groups
                                              should be used as role names and assigned to the user.
                                              A group is considered to be _unmapped_ if it is not referenced
                                              in any <<mapping-roles-file, role-mapping files>> (API based
                                              role-mappings are not considered).
                                              Defaults to `false`.
| `timeout.tcp_connect`          | no       | Specifies the TCP connect timeout period for establishing an
                                              LDAP connection. An `s` at the end indicates seconds, or `ms`
                                              indicates milliseconds. Defaults to `5s` (5 seconds).
| `timeout.tcp_read`             | no       | Specifies the TCP read timeout period after establishing an LDAP connection.
                                              An `s` at the end indicates seconds, or `ms` indicates milliseconds.
                                              Defaults to `5s` (5 seconds).
| `timeout.ldap_search`          | no       | Specifies the LDAP Server enforced timeout period for an LDAP search.
                                              An `s` at the end indicates seconds, or `ms` indicates milliseconds.
                                              Defaults to `5s` (5 seconds).
| `files.role_mapping`           | no       | Specifies the path and file name for the
                                              <<ldap-role-mapping, YAML role mapping configuration file>>.
                                              Defaults to `ES_HOME/config/x-pack/role_mapping.yml`.
| `follow_referrals`             | no       | Specifies whether {security} should follow referrals
                                              returned by the LDAP server. Referrals are URLs returned by
                                              the server that are to be used to continue the LDAP operation
                                              (e.g. search). Defaults to `true`.
| `metadata`                     | no       | Specifies the list of additional LDAP attributes that should
                                              be stored in the `metadata` of an authenticated user.
| `ssl.key`                      | no       | Specifies the path to the PEM encoded private key to use if the LDAP
                                              server requires client authentication. `ssl.key` and `ssl.keystore.path`
                                              may not be used at the same time.
| `ssl.key_passphrase`           | no       | Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted.
| `ssl.certificate`              | no       | Specifies the path to the PEM encoded certificate (or certificate chain) that goes with the
                                              key if the LDAP server requires client authentication.
| `ssl.certificate_authorities`  | no       | Specifies the paths to the PEM encoded certificate authority certificates that
                                              should be trusted. `ssl.certificate_authorities` and `ssl.trustsore.path` may not be used
                                              at the same time.
| `ssl.keystore.path`            | no       | The path to the Java Keystore file that contains a private key and certificate. `ssl.key` and
                                              `ssl.keystore.path` may not be used at the same time.
| `ssl.keystore.password`        | no       | The password to the keystore.
| `ssl.keystore.key_password`    | no       | The password for the key in the keystore. Defaults to the keystore password.
| `ssl.truststore.path`          | no       | The path to the Java Keystore file that contains the certificates to trust.
                                              `ssl.certificate_authorities` and `ssl.trustsore.path` may not be used at the same time.
| `ssl.truststore.password`      | no       | The password to the truststore.
| `ssl.verification_mode`        | no       | Specifies the type of verification to be performed when
                                              connecting to a LDAP server using `ldaps`. When
                                              set to `full`, the hostname or IP address used in the `url`
                                              must match one of the names in the certificate or the
                                              connection will not be allowed. Due to their potential security impact,
                                              `ssl` settings are not exposed via the
                                              {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
                                              Values are `none`, `certificate`, and `full`. Defaults to `full`.
| `ssl.supported_protocols`      | no       | Specifies the supported protocols for SSL/TLS.
| `ssl.cipher_suites`            | no       | Specifies the cipher suites that should be supported when communicating
                                              with the LDAP server.
| `cache.ttl`                | no           | Specifies the time-to-live for cached user entries. A
                                              user's credentials are cached for this period of time.
                                              Specify the time period using the standard Elasticsearch
                                              {ref}/common-options.html#time-units[time units].
                                              Defaults to `20m`.
| `cache.max_users`          | no           | Specifies the maximum number of user entries that can be
                                              stored in the cache at one time. Defaults to 100,000.
| `cache.hash_algo`          | no           | Specifies the hashing algorithm that is used for the
                                              cached user credentials. See
                                              <<cache-hash-algo, Cache hash algorithms>> for the possible
                                              values. (Expert Setting).
|=======================

.User Search Mode Settings
|=======================
| Setting                                  | Required | Description
| `bind_dn`                                | no       | The DN of the user that is used to bind to the LDAP
                                                        and perform searches. If not specified, an anonymous
                                                        bind is attempted. Due to its potential security
                                                        impact, `bind_dn` is not exposed via the
                                                        {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
| `bind_password`                          | no       | The password for the user that is used to bind to the
                                                        LDAP. Due to its potential security impact,  
                                                        `bind_password` is not exposed via the
                                                        {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
| `user_search.base_dn`                    | yes      | Specifies a container DN to search for users.
| `user_search.scope`                      | no       | The scope of the user search. Valid values are `sub_tree`,
                                                        `one_level` or `base`. `one_level` only searches objects
                                                        directly contained within the `base_dn`. `sub_tree` searches
                                                        all objects contained under `base_dn`. `base` specifies
                                                        that the `base_dn` is the user object, and that it is the
                                                        only user considered. Defaults to `sub_tree`.
| `user_search.attribute`                  | no       | Specifies the attribute to match with the username presented
                                                        to. Defaults to `uid`.
| `user_search.pool.enabled`               | no       | Enables or disables connection pooling for user search. When
                                                        disabled a new connection is created for every search. The
                                                        default is `true`.
| `user_search.pool.size`                  | no       | Specifies the maximum number of connections to the LDAP
                                                        server to allow in the connection pool. Defaults to `20`.
| `user_search.pool.initial_size`          | no       | The initial number of connections to create to the LDAP
                                                        server on startup. Defaults to `0`. Values greater than `0`
                                                        could cause startup failures if the LDAP server is down.
| `user_search.pool.health_check.enabled`  | no       | Enables or disables a health check on LDAP connections in
                                                        the connection pool. Connections are checked in the
                                                        background at the specified interval. Defaults to `true`.
| `user_search.pool.health_check.dn`       | no/yes   | Specifies the distinguished name to retrieve as part of
                                                        the health check. Defaults to the value of `bind_dn`.
                                                        This setting is required when `bind_dn` is not configured.
| `user_search.pool.health_check.interval` | no       | How often to perform background checks of connections in
                                                        the pool. Defaults to `60s`.
|=======================

.User Templates Mode Settings
[cols="4,^3,10"]
|=======================
| Setting               | Required  | Description
| `user_dn_templates`   | yes       | Specifies the DN template that replaces the
                                      user name with the string `{0}`. This element
                                      is multivalued, allowing for multiple user
                                      contexts.
|=======================


NOTE:   If any settings starting with `user_search` are specified, the
        `user_dn_templates` the settings are ignored.


[[mapping-roles-ldap]]
==== Mapping LDAP Groups to Roles

An integral part of a realm authentication process is to resolve the roles
associated with the authenticated user. Roles define the privileges a user has
in the cluster.

Since with the `ldap` realm the users are managed externally in the LDAP server,
the expectation is that their roles are managed there as well. If fact, LDAP
supports the notion of groups, which often represent user roles for different
systems in the organization.

The `ldap` realm enables you to map LDAP users to to roles via their LDAP
groups, or other metadata. This role mapping can be configured via the
<<security-api-role-mapping, role-mapping API>>, or by using a file stored
on each node. When a user authenticates with LDAP, the privileges
for that user are the union of all privileges defined by the roles to which
the user is mapped.

Within a mapping definition, you specify groups using their distinguished
names. For example, the following mapping configuration maps the LDAP
`admins` group to both the `monitoring` and `user` roles, and maps the
`users` group to the `user` role.

Configured via the role-mapping API:
[source,js]
--------------------------------------------------
PUT _xpack/security/role_mapping/admins
{
  "roles" : [ "monitoring" , "user" ],
  "rules" : { "field" : {
    "groups" : "cn=admins,dc=example,dc=com" <1>
  } },
  "enabled": true
}
--------------------------------------------------
// CONSOLE
<1> The LDAP distinguished name (DN) of the `admins` group.

[source,js]
--------------------------------------------------
PUT _xpack/security/role_mapping/basic_users
{
  "roles" : [ "user" ],
  "rules" : { "field" : {
    "groups" : "cn=users,dc=example,dc=com" <1>
  } },
  "enabled": true
}
--------------------------------------------------
// CONSOLE
<1> The LDAP distinguished name (DN) of the `users` group.

Or, alternatively, configured via the role-mapping file:
[source, yaml]
------------------------------------------------------------
monitoring: <1>
  - "cn=admins,dc=example,dc=com" <2>
user:
  - "cn=users,dc=example,dc=com" <3>
  - "cn=admins,dc=example,dc=com"
------------------------------------------------------------
<1> The name of the mapped role.
<2> The LDAP distinguished name (DN) of the `admins` group.
<3> The LDAP distinguished name (DN) of the `users` group.

For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.

[[ldap-user-metadata]]
==== User Metadata in LDAP Realms
When a user is authenticated via an LDAP realm, the following properties are
populated in user's _metadata_. This metadata is returned in the
<<security-api-authenticate,authenticate API>>, and can be used with
<<templating-role-query, templated queries>> in roles.

|=======================
| Field               | Description
| `ldap_dn`           | The distinguished name of the user.
| `ldap_groups`       | The distinguished name of each of the groups that were
                        resolved for the user (regardless of whether those
                        groups were mapped to a role).
|=======================

Additional fields can be included in the user's metadata by  configuring
the `metadata` setting on the LDAP realm. This metadata is available for use
with the <<mapping-roles-api, role mapping API>> or in
<<templating-role-query, templated role queries>>.

The example below includes the user's common name (`cn`) as an additional
field in their metadata.
[source,yaml]
--------------------------------------------------
xpack:
  security:
    authc:
      realms:
        ldap1:
          type: ldap
          metadata: cn
--------------------------------------------------

[[ldap-ssl]]
==== Setting up SSL Between Elasticsearch and LDAP

To protect the user credentials that are sent for authentication, it's highly
recommended to encrypt communications between Elasticsearch and your LDAP server.
Connecting via SSL/TLS ensures that the identity of the LDAP server is
authenticated before {security} transmits the user credentials and the contents
of the connection are encrypted.

To encrypt communications between Elasticsearch and your LDAP server:

. Configure the realm's SSL settings on each node to trust certificates signed by the CA that signed your
LDAP server certificates. The following example demonstrates how to trust a CA certificate,
`cacert.pem`, located within the {xpack} configuration directory:
+
[source,shell]
--------------------------------------------------
xpack:
  security:
    authc:
      realms:
        ldap1:
          type: ldap
          order: 0
          url: "ldaps://ldap.example.com:636"
          ssl:
            certificate_authorities: [ "CONFIG_DIR/x-pack/cacert.pem" ]
--------------------------------------------------
+
The CA cert must be a PEM encoded certificate.
+
[NOTE]
===============================
You can also specify the individual server certificates rather than the CA
certificate, but this is only recommended if you have a single LDAP server
or the certificates are self-signed.
===============================

. Set the `url` attribute in the realm configuration to specify the LDAPS
protocol and the secure port number. For example, `url: ldaps://ldap.example.com:636`.

. Restart Elasticsearch.

NOTE: By default, when you configure {security} to connect to an LDAP server
      using SSL/TLS, {security} attempts to verify the hostname or IP address
      specified with the `url` attribute in the realm configuration with the
      values in the certificate. If the values in the certificate and realm
      configuration do not match, {security} does not allow a connection to the
      LDAP server. This is done to protect against man-in-the-middle attacks. If
      necessary, you can disable this behavior by setting the
      `ssl.verification_mode` property to `none`.
