[[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 <>. 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 <>. ==== 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 <> 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 <> 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" 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 ------------------------------------------------------------ + The password for the `bind_dn` user should be configured by adding the appropriate `secure_bind_password` setting to the {es} keystore. For example, the following command adds the password for the example realm above: + [source, shell] ------------------------------------------------------------ bin/elasticsearch-keystore add xpack.security.authc.realms.ldap1.secure_bind_password ------------------------------------------------------------ + 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 DN templates: . 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 <> 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 IMPORTANT: The `bind_dn` setting is not used in template mode. All LDAP operations will execute as the authenticating user. [[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. See {ref}/security-settings.html#load-balancing[Load Balancing and Failover Settings]. [[ldap-settings]] ===== LDAP Realm Settings See {ref}/security-settings.html#ref-ldap-settings[LDAP Realm Settings]. [[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 {ref}/security-api-role-mapping.html[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 <>. [[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 {ref}/security-api-authenticate.html[authenticate API], and can be used with <> 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 <> or in <>. 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 `certificate`.