LDAP User Authentication

You can configure X-Pack 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 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 Setting up SSL Between Elasticsearch and LDAP.

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 Realm Settings for all of the options you can set for an ldap realm.

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:

  1. 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 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:

    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.

  2. 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 DN templates:

  1. 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 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:

    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
  2. Restart Elasticsearch
Important

The bind_dn setting is not used in template mode. All LDAP operations will execute as the authenticating user.

Load Balancing and Failover

The load_balance.type setting can be used at the realm level to configure how X-Pack security should interact with multiple LDAP servers. X-Pack security supports both failover and load balancing modes of operation.

Table 5. 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 Realm Settings

Table 6. Common LDAP Realm Settings

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 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 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 YAML role mapping configuration file. Defaults to ES_HOME/config/x-pack/role_mapping.yml.

follow_referrals

no

Specifies whether X-Pack 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.truststore.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.truststore.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 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 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 algorithms for the possible values. (Expert Setting).


Table 7. 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 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 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.


Table 8. User Templates Mode Settings

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 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 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:

PUT _xpack/security/role_mapping/admins
{
  "roles" : [ "monitoring" , "user" ],
  "rules" : { "field" : {
    "groups" : "cn=admins,dc=example,dc=com" 
  } },
  "enabled": true
}

The LDAP distinguished name (DN) of the admins group.

PUT _xpack/security/role_mapping/basic_users
{
  "roles" : [ "user" ],
  "rules" : { "field" : {
    "groups" : "cn=users,dc=example,dc=com" 
  } },
  "enabled": true
}

The LDAP distinguished name (DN) of the users group.

Or, alternatively, configured via the role-mapping file:

monitoring: 
  - "cn=admins,dc=example,dc=com" 
user:
  - "cn=users,dc=example,dc=com" 
  - "cn=admins,dc=example,dc=com"

The name of the mapped role.

The LDAP distinguished name (DN) of the admins group.

The LDAP distinguished name (DN) of the users group.

For more information, see Mapping Users and Groups to Roles.

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 authenticate API, and can be used with 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 role mapping API or in templated role queries.

The example below includes the user’s common name (cn) as an additional field in their metadata.

xpack:
  security:
    authc:
      realms:
        ldap1:
          type: ldap
          metadata: cn

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 X-Pack security transmits the user credentials and the contents of the connection are encrypted.

To encrypt communications between Elasticsearch and your LDAP server:

  1. 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 X-Pack configuration directory:

    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.

  2. 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.
  3. Restart Elasticsearch.
Note

By default, when you configure X-Pack security to connect to an LDAP server using SSL/TLS, X-Pack 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, X-Pack 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.