300 lines
12 KiB
Plaintext
300 lines
12 KiB
Plaintext
[[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"
|
|
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 <<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
|
|
|
|
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 <<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
|
|
{ref}/security-api-authenticate.html[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 `certificate`.
|