You can configure Elasticsearch to authenticate users by communicating with a Lightweight
Directory Access Protocol (LDAP) server. To integrate with LDAP, you configure
an ldap
realm and map LDAP groups to user roles.
For more information about LDAP realms, see LDAP User Authentication.
Determine which mode you want to use. The ldap
realm supports two modes of
operation, a user search mode and a mode with specific templates for user DNs.
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 DN of the authenticating user based on the provided username and an LDAP attribute. Once found, the user is authenticated by attempting to bind to the LDAP server using the found DN and the provided password.
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 to elasticsearch.yml
under the
xpack.security.authc.realms.ldap
namespace. At a minimum, you must 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: ldap: ldap1: order: 0 url: "ldaps://ldap.example.com:636" bind_dn: "cn=ldapuser, ou=users, o=services, dc=example, dc=com" 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/role_mapping.yml" unmapped_groups_as_roles: false
The password for the bind_dn
user should be configured by adding the appropriate
secure_bind_password
setting to the Elasticsearch keystore.
For example, the following command adds the password for the example realm above:
bin/elasticsearch-keystore add \ xpack.security.authc.realms.ldap.ldap1.secure_bind_password
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.
To configure an ldap
realm with user DN templates:
Add a realm configuration to elasticsearch.yml
in the
xpack.security.authc.realms.ldap
namespace. At a minimum, you must 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: ldap: ldap1: 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
The bind_dn
setting is not used in template mode.
All LDAP operations run as the authenticating user.
(Optional) Configure how the security features interact with multiple LDAP servers.
The load_balance.type
setting can be used at the realm level. The Elasticsearch
security features support both failover and load balancing modes of operation.
See LDAP realm settings.
Map LDAP groups to roles.
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
add 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 /_security/role_mapping/admins { "roles" : [ "monitoring" , "user" ], "rules" : { "field" : { "groups" : "cn=admins,dc=example,dc=com" } }, "enabled": true }
PUT /_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 LDAP Groups to Roles and Mapping Users and Groups to Roles.
The LDAP realm supports authorization realms as an alternative to role mapping.
(Optional) Configure the metadata
setting on the LDAP realm to include extra
fields in the user’s metadata.
By default, ldap_dn
and ldap_groups
are populated in the user’s metadata.
For more information, see
User Metadata in LDAP Realms.
The example below includes the user’s common name (cn
) as an additional
field in their metadata.
xpack: security: authc: realms: ldap: ldap1: metadata: cn