mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-08 05:58:44 +00:00
574ec6686e
This moves all Realm settings to an Affix definition.
However, because different realm types define different settings
(potentially conflicting settings) this requires that the realm type
become part of the setting key.
Thus, we now need to define realm settings as:
xpack.security.authc.realms:
file.file1:
order: 0
native.native1:
order: 1
- This is a breaking change to realm config
- This is also a breaking change to custom security realms (SecurityExtension)
220 lines
7.7 KiB
Plaintext
220 lines
7.7 KiB
Plaintext
[role="xpack"]
|
|
[[configuring-ldap-realm]]
|
|
=== Configuring an LDAP realm
|
|
|
|
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.
|
|
|
|
For more information about LDAP realms, see
|
|
{xpack-ref}/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"
|
|
attribute: cn
|
|
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 {security} should interact with multiple LDAP servers.
|
|
+
|
|
--
|
|
The `load_balance.type` setting can be used at the realm level. {security}
|
|
supports 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 _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
|
|
{xpack-ref}/ldap-realm.html#mapping-roles-ldap[Mapping LDAP Groups to Roles]
|
|
and
|
|
{xpack-ref}/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
|
|
{xpack-ref}/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
|
|
--------------------------------------------------
|
|
--
|