WARNING: Version 6.2 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.
LDAP User Authentication
editLDAP User Authentication
editYou 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
editLDAP 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
editLDAP 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
toelasticsearch.yml
under thexpack.security.authc.realms
namespace. At a minimum, you must set the realmtype
toldap
, specify theurl
of the LDAP server, and setuser_search.base_dn
to the container DN where the users are searched for. If you are configuring multiple realms, you should also explicitly set theorder
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 anldap
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: x-pack-test-password user_search: base_dn: "dc=example,dc=com" filter: "(cn={0})" group_search: base_dn: "dc=example,dc=com" files: role_mapping: "ES_PATH_CONF/x-pack/role_mapping.yml" unmapped_groups_as_roles: false
When you configure realms in
elasticsearch.yml
, only the realms you specify are used for authentication. If you also want to use thenative
orfile
realms, you must include them in the realm chain. - Restart Elasticsearch
User DN Templates Mode
editIf 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:
-
Add a realm configuration of type
ldap
toelasticsearch.yml
in thexpack.security.authc.realms
namespace. At a minimum, you must set the realmtype
toldap
, specify theurl
of the LDAP server, and specify at least one template with theuser_dn_templates
option. If you are configuring multiple realms, you should also explicitly set theorder
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 anldap
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
- Restart Elasticsearch
The bind_dn
setting is not used in template mode.
All LDAP operations will execute as the authenticating user.
Load Balancing and Failover
editThe 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 1. Load Balancing and Failover Types
Type |
Description |
||
|
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. |
||
|
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 |
||
|
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. |
||
|
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
editTable 2. Common LDAP Realm Settings
Setting |
Required |
Description |
|
yes |
Indicates the realm type. Must be set to |
|
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 |
|
no |
Indicates whether this realm is enabled or disabled.
Enables you to disable a realm without removing its
configuration. Defaults to |
|
yes |
Specifies one or more LDAP URLs of the form of
|
|
no |
The behavior to use when there are multiple LDAP URLs defined. For supported values see LDAP load balancing and failover types. |
|
no |
When using |
|
no |
Specifies the attribute to examine on the user for group
membership. The default is |
|
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
|
|
no |
Specifies whether the group search should be
|
|
no |
Specifies a filter to use to lookup a group. If not
set, the realm searches for |
|
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. |
|
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 |
|
no |
Specifies the TCP connect timeout period for establishing an
LDAP connection. An |
|
no |
Specifies the TCP read timeout period after establishing an LDAP connection.
An |
|
no |
Specifies the LDAP Server enforced timeout period for an LDAP search.
An |
|
no |
Specifies the path and file name for the
YAML role mapping configuration file.
Defaults to |
|
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 |
|
no |
Specifies the list of additional LDAP attributes that should
be stored in the |
|
no |
Specifies the path to the PEM encoded private key to use if the LDAP
server requires client authentication. |
|
no |
Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted. |
|
no |
Specifies the path to the PEM encoded certificate (or certificate chain) that goes with the key if the LDAP server requires client authentication. |
|
no |
Specifies the paths to the PEM encoded certificate authority certificates that
should be trusted. |
|
no |
The path to the Java Keystore file that contains a private key and certificate. |
|
no |
The password to the keystore. |
|
no |
The password for the key in the keystore. Defaults to the keystore password. |
|
no |
The path to the Java Keystore file that contains the certificates to trust.
|
|
no |
The password to the truststore. |
|
no |
Specifies the type of verification to be performed when
connecting to a LDAP server using |
|
no |
Specifies the supported protocols for SSL/TLS. |
|
no |
Specifies the cipher suites that should be supported when communicating with the LDAP server. |
|
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 |
|
no |
Specifies the maximum number of user entries that can be stored in the cache at one time. Defaults to 100,000. |
|
no |
Specifies the hashing algorithm that is used for the cached user credentials. See Cache hash algorithms for the possible values. (Expert Setting). |
Table 3. User Search Mode Settings
Setting |
Required |
Description |
|
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, |
|
no |
The password for the user that is used to bind to the
LDAP. Due to its potential security impact,
|
|
yes |
Specifies a container DN to search for users. |
|
no |
The scope of the user search. Valid values are |
|
no |
Specifies the filter used to search the directory in attempt to match
an entry with the username provided by the user. Defaults to |
|
no |
This setting is deprecated; use |
|
no |
Enables or disables connection pooling for user search. When
disabled a new connection is created for every search. The
default is |
|
no |
Specifies the maximum number of connections to the LDAP
server to allow in the connection pool. Defaults to |
|
no |
The initial number of connections to create to the LDAP
server on startup. Defaults to |
|
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 |
|
no/yes |
Specifies the distinguished name to retrieve as part of
the health check. Defaults to the value of |
|
no |
How often to perform background checks of connections in
the pool. Defaults to |
Table 4. User Templates Mode Settings
Setting |
Required |
Description |
|
yes |
Specifies the DN template that replaces the
user name with the string |
If any settings starting with user_search
are specified, the
user_dn_templates
the settings are ignored.
Mapping LDAP Groups to Roles
editAn 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 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 }
PUT _xpack/security/role_mapping/basic_users { "roles" : [ "user" ], "rules" : { "field" : { "groups" : "cn=users,dc=example,dc=com" } }, "enabled": true }
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 |
|
The LDAP distinguished name (DN) of the |
For more information, see Mapping Users and Groups to Roles.
User Metadata in LDAP Realms
editWhen 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 |
|
The distinguished name of the user. |
|
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
editTo 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:
-
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: [ "ES_PATH_CONF/x-pack/cacert.pem" ]
The CA cert must be a PEM encoded certificate.
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.
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 certificate
.