221 lines
7.7 KiB
Plaintext
221 lines
7.7 KiB
Plaintext
[role="xpack"]
|
|
[[configuring-ldap-realm]]
|
|
=== Configuring an LDAP realm
|
|
|
|
You can configure {es} 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
|
|
{stack-ov}/ldap-realm.html[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 <<ref-ldap-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:
|
|
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 {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.ldap.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.
|
|
|
|
--
|
|
|
|
. 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 <<ref-ldap-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:
|
|
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
|
|
------------------------------------------------------------
|
|
|
|
IMPORTANT: 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 {es}
|
|
{security-features} support both failover and load balancing modes of operation.
|
|
See <<ref-ldap-settings>>.
|
|
--
|
|
|
|
. (Optional) To protect passwords,
|
|
<<tls-ldap,encrypt communications between {es} and the LDAP server>>.
|
|
|
|
. Restart {es}.
|
|
|
|
. Map LDAP groups to roles.
|
|
+
|
|
--
|
|
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-put-role-mapping.html[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:
|
|
[source,js]
|
|
--------------------------------------------------
|
|
PUT /_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 /_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
|
|
{stack-ov}/ldap-realm.html#mapping-roles-ldap[Mapping LDAP Groups to Roles]
|
|
and
|
|
{stack-ov}/mapping-roles.html[Mapping Users and Groups to Roles].
|
|
|
|
NOTE: The LDAP realm supports
|
|
{stack-ov}/realm-chains.html#authorization_realms[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
|
|
{stack-ov}/ldap-realm.html#ldap-user-metadata[User Metadata in LDAP Realms].
|
|
|
|
The example below includes the user's common name (`cn`) as an additional
|
|
field in their metadata.
|
|
[source,yaml]
|
|
--------------------------------------------------
|
|
xpack:
|
|
security:
|
|
authc:
|
|
realms:
|
|
ldap:
|
|
ldap1:
|
|
metadata: cn
|
|
--------------------------------------------------
|
|
--
|