478 lines
28 KiB
Plaintext
478 lines
28 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"
|
|
bind_password: x-pack-test-password
|
|
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
|
|
------------------------------------------------------------
|
|
+
|
|
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 Search:
|
|
|
|
. 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
|
|
|
|
|
|
[[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.
|
|
|
|
.Load Balancing and Failover Types
|
|
|=======================
|
|
| Type | | | Description
|
|
| `failover` | | | The URLs specified are used in the order that they are specified.
|
|
The first server that can be connected to will be used for all
|
|
subsequent connections. If a connection to that server fails then
|
|
the next server that a connection can be established to will be
|
|
used for subsequent connections.
|
|
| `dns_failover` | | | In this mode of operation, only a single URL may be specified.
|
|
This URL must contain a DNS name. The system will be queried for
|
|
all IP addresses that correspond to this DNS name. Connections to
|
|
the LDAP server will always be tried in the order in which they
|
|
were retrieved. This differs from `failover` in that there is no
|
|
reordering of the list and if a server has failed at the beginning
|
|
of the list, it will still be tried for each subsequent connection.
|
|
| `round_robin` | | | Connections will continuously iterate through the list of provided
|
|
URLs. If a server is unavailable, iterating through the list of
|
|
URLs will continue until a successful connection is made.
|
|
| `dns_round_robin` | | | In this mode of operation, only a single URL may be specified. This
|
|
URL must contain a DNS name. The system will be queried for all IP
|
|
addresses that correspond to this DNS name. Connections will
|
|
continuously iterate through the list of addresses. If a server is
|
|
unavailable, iterating through the list of URLs will continue until
|
|
a successful connection is made.
|
|
|=======================
|
|
|
|
|
|
[[ldap-settings]]
|
|
===== LDAP Realm Settings
|
|
|
|
.Common LDAP Realm Settings
|
|
[cols="4,^3,10"]
|
|
|=======================
|
|
| Setting | Required | Description
|
|
| `type` | yes | Indicates the realm type. Must be set to `ldap`.
|
|
| `order` | no | Indicates the priority of this realm within the realm
|
|
chain. Realms with a lower order are consulted first.
|
|
Although not required, we recommend explicitly
|
|
setting this value when you configure multiple realms.
|
|
Defaults to `Integer.MAX_VALUE`.
|
|
| `enabled` | no | Indicates whether this realm is enabled or disabled.
|
|
Enables you to disable a realm without removing its
|
|
configuration. Defaults to `true`.
|
|
| `url` | yes | Specifies one or more LDAP URLs of the form of
|
|
`ldap[s]://<server>:<port>`. Multiple URLs can be
|
|
defined using a comma separated value or array syntax:
|
|
`[ "ldaps://server1:636", "ldaps://server2:636" ]`.
|
|
`ldaps` and `ldap` URL protocols cannot be mixed in
|
|
the same realm.
|
|
| `load_balance.type` | no | The behavior to use when there are multiple LDAP URLs
|
|
defined. For supported values see
|
|
<<ldap-load-balancing, LDAP load balancing and failover types>>.
|
|
| `load_balance.cache_ttl` | no | When using `dns_failover` or `dns_round_robin` as the
|
|
load balancing type, this setting controls the amount of time
|
|
to cache DNS lookups. Defaults to `1h`.
|
|
| `user_group_attribute` | no | Specifies the attribute to examine on the user for group
|
|
membership. The default is `memberOf`. This setting will
|
|
be ignored if any `group_search` settings are specified.
|
|
| `group_search.base_dn` | no | Specifies a container DN to search for groups in which
|
|
the user has membership. When this element is absent,
|
|
Security searches for the attribute specified by
|
|
`user_group_attribute` set on the user to determine
|
|
group membership.
|
|
| `group_search.scope` | no | Specifies whether the group search should be
|
|
`sub_tree`, `one_level` or `base`. `one_level` only
|
|
searches objects directly contained within the
|
|
`base_dn`. The default `sub_tree` searches all objects
|
|
contained under `base_dn`. `base` specifies that the
|
|
`base_dn` is a group object, and that it is the only
|
|
group considered.
|
|
| `group_search.filter` | no | Specifies a filter to use to lookup a group. If not
|
|
set, the realm searches for `group`,
|
|
`groupOfNames`, `groupOfUniqueNames`, or `posixGroup` with the
|
|
attributes `member`, `memberOf`, or `memberUid`. Any instance of
|
|
`{0}` in the filter is replaced by the user
|
|
attribute defined in `group_search.user_attribute`
|
|
| `group_search.user_attribute` | no | Specifies the user attribute that is fetched and
|
|
provided as a parameter to the filter. If not set,
|
|
the user DN is passed to the filter.
|
|
| `unmapped_groups_as_roles` | no | Specifies whether the names of any unmapped LDAP groups
|
|
should be used as role names and assigned to the user.
|
|
A group is considered to be _unmapped_ if it is not referenced
|
|
in any <<mapping-roles-file, role-mapping files>> (API based
|
|
role-mappings are not considered).
|
|
Defaults to `false`.
|
|
| `timeout.tcp_connect` | no | Specifies the TCP connect timeout period for establishing an
|
|
LDAP connection. An `s` at the end indicates seconds, or `ms`
|
|
indicates milliseconds. Defaults to `5s` (5 seconds).
|
|
| `timeout.tcp_read` | no | Specifies the TCP read timeout period after establishing an LDAP connection.
|
|
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
|
|
Defaults to `5s` (5 seconds).
|
|
| `timeout.ldap_search` | no | Specifies the LDAP Server enforced timeout period for an LDAP search.
|
|
An `s` at the end indicates seconds, or `ms` indicates milliseconds.
|
|
Defaults to `5s` (5 seconds).
|
|
| `files.role_mapping` | no | Specifies the path and file name for the
|
|
<<ldap-role-mapping, YAML role mapping configuration file>>.
|
|
Defaults to `ES_HOME/config/x-pack/role_mapping.yml`.
|
|
| `follow_referrals` | no | Specifies whether {security} should follow referrals
|
|
returned by the LDAP server. Referrals are URLs returned by
|
|
the server that are to be used to continue the LDAP operation
|
|
(e.g. search). Defaults to `true`.
|
|
| `metadata` | no | Specifies the list of additional LDAP attributes that should
|
|
be stored in the `metadata` of an authenticated user.
|
|
| `ssl.key` | no | Specifies the path to the PEM encoded private key to use if the LDAP
|
|
server requires client authentication. `ssl.key` and `ssl.keystore.path`
|
|
may not be used at the same time.
|
|
| `ssl.key_passphrase` | no | Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted.
|
|
| `ssl.certificate` | no | Specifies the path to the PEM encoded certificate (or certificate chain) that goes with the
|
|
key if the LDAP server requires client authentication.
|
|
| `ssl.certificate_authorities` | no | Specifies the paths to the PEM encoded certificate authority certificates that
|
|
should be trusted. `ssl.certificate_authorities` and `ssl.trustsore.path` may not be used
|
|
at the same time.
|
|
| `ssl.keystore.path` | no | The path to the Java Keystore file that contains a private key and certificate. `ssl.key` and
|
|
`ssl.keystore.path` may not be used at the same time.
|
|
| `ssl.keystore.password` | no | The password to the keystore.
|
|
| `ssl.keystore.key_password` | no | The password for the key in the keystore. Defaults to the keystore password.
|
|
| `ssl.truststore.path` | no | The path to the Java Keystore file that contains the certificates to trust.
|
|
`ssl.certificate_authorities` and `ssl.trustsore.path` may not be used at the same time.
|
|
| `ssl.truststore.password` | no | The password to the truststore.
|
|
| `ssl.verification_mode` | no | Specifies the type of verification to be performed when
|
|
connecting to a LDAP server using `ldaps`. When
|
|
set to `full`, the hostname or IP address used in the `url`
|
|
must match one of the names in the certificate or the
|
|
connection will not be allowed. Due to their potential security impact,
|
|
`ssl` settings are not exposed via the
|
|
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
|
|
Values are `none`, `certificate`, and `full`. Defaults to `full`.
|
|
| `ssl.supported_protocols` | no | Specifies the supported protocols for SSL/TLS.
|
|
| `ssl.cipher_suites` | no | Specifies the cipher suites that should be supported when communicating
|
|
with the LDAP server.
|
|
| `cache.ttl` | no | Specifies the time-to-live for cached user entries. A
|
|
user's credentials are cached for this period of time.
|
|
Specify the time period using the standard Elasticsearch
|
|
{ref}/common-options.html#time-units[time units].
|
|
Defaults to `20m`.
|
|
| `cache.max_users` | no | Specifies the maximum number of user entries that can be
|
|
stored in the cache at one time. Defaults to 100,000.
|
|
| `cache.hash_algo` | no | Specifies the hashing algorithm that is used for the
|
|
cached user credentials. See
|
|
<<cache-hash-algo, Cache hash algorithms>> for the possible
|
|
values. (Expert Setting).
|
|
|=======================
|
|
|
|
.User Search Mode Settings
|
|
|=======================
|
|
| Setting | Required | Description
|
|
| `bind_dn` | no | The DN of the user that is used to bind to the LDAP
|
|
and perform searches. If not specified, an anonymous
|
|
bind is attempted. Due to its potential security
|
|
impact, `bind_dn` is not exposed via the
|
|
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
|
|
| `bind_password` | no | The password for the user that is used to bind to the
|
|
LDAP. Due to its potential security impact,
|
|
`bind_password` is not exposed via the
|
|
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
|
|
| `user_search.base_dn` | yes | Specifies a container DN to search for users.
|
|
| `user_search.scope` | no | The scope of the user search. Valid values are `sub_tree`,
|
|
`one_level` or `base`. `one_level` only searches objects
|
|
directly contained within the `base_dn`. `sub_tree` searches
|
|
all objects contained under `base_dn`. `base` specifies
|
|
that the `base_dn` is the user object, and that it is the
|
|
only user considered. Defaults to `sub_tree`.
|
|
| `user_search.attribute` | no | Specifies the attribute to match with the username presented
|
|
to. Defaults to `uid`.
|
|
| `user_search.pool.enabled` | no | Enables or disables connection pooling for user search. When
|
|
disabled a new connection is created for every search. The
|
|
default is `true`.
|
|
| `user_search.pool.size` | no | Specifies the maximum number of connections to the LDAP
|
|
server to allow in the connection pool. Defaults to `20`.
|
|
| `user_search.pool.initial_size` | no | The initial number of connections to create to the LDAP
|
|
server on startup. Defaults to `0`. Values greater than `0`
|
|
could cause startup failures if the LDAP server is down.
|
|
| `user_search.pool.health_check.enabled` | no | Enables or disables a health check on LDAP connections in
|
|
the connection pool. Connections are checked in the
|
|
background at the specified interval. Defaults to `true`.
|
|
| `user_search.pool.health_check.dn` | no/yes | Specifies the distinguished name to retrieve as part of
|
|
the health check. Defaults to the value of `bind_dn`.
|
|
This setting is required when `bind_dn` is not configured.
|
|
| `user_search.pool.health_check.interval` | no | How often to perform background checks of connections in
|
|
the pool. Defaults to `60s`.
|
|
|=======================
|
|
|
|
.User Templates Mode Settings
|
|
[cols="4,^3,10"]
|
|
|=======================
|
|
| Setting | Required | Description
|
|
| `user_dn_templates` | yes | Specifies the DN template that replaces the
|
|
user name with the string `{0}`. This element
|
|
is multivalued, allowing for multiple user
|
|
contexts.
|
|
|=======================
|
|
|
|
|
|
NOTE: If any settings starting with `user_search` are specified, the
|
|
`user_dn_templates` the settings are ignored.
|
|
|
|
|
|
[[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 `none`.
|