[DOCS] Adds LDAP realm configuration details (#30214)
This commit is contained in:
Lisa Cawley
GitHub
parent
5064ff6ad4
commit
383856a175
|
|
@ -0,0 +1,214 @@
|
|||
[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 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 <<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:
|
||||
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.
|
||||
|
||||
--
|
||||
|
||||
. 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
|
||||
<<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:
|
||||
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
|
||||
------------------------------------------------------------
|
||||
|
||||
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-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
|
||||
{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].
|
||||
--
|
||||
|
||||
. (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:
|
||||
ldap1:
|
||||
type: ldap
|
||||
metadata: cn
|
||||
--------------------------------------------------
|
||||
--
|
||||
|
|
@ -1,19 +1,11 @@
|
|||
[[ldap-realm]]
|
||||
=== LDAP User Authentication
|
||||
=== 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
|
||||
|
|
@ -25,128 +17,28 @@ _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.
|
||||
and a mode with specific templates for user DNs.
|
||||
|
||||
[[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.
|
||||
===== User search mode and user DN templates mode
|
||||
|
||||
See {ref}/configuring-ldap-realm.html[Configuring an LDAP Realm].
|
||||
|
||||
[[ldap-load-balancing]]
|
||||
===== Load Balancing and Failover
|
||||
===== 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
|
||||
===== LDAP realm settings
|
||||
|
||||
See {ref}/security-settings.html#ref-ldap-settings[LDAP Realm Settings].
|
||||
|
||||
[[mapping-roles-ldap]]
|
||||
==== Mapping LDAP Groups to Roles
|
||||
==== 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
|
||||
|
|
@ -162,63 +54,13 @@ 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>>.
|
||||
the user is mapped. For more information, see
|
||||
{ref}/configuring-ldap-realm.html[Configuring an LDAP Realm].
|
||||
|
||||
[[ldap-user-metadata]]
|
||||
==== User Metadata in LDAP Realms
|
||||
==== 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.
|
||||
populated in the user's _metadata_:
|
||||
|
||||
|=======================
|
||||
| Field | Description
|
||||
|
|
@ -228,72 +70,16 @@ populated in user's _metadata_. This metadata is returned in the
|
|||
groups were mapped to a role).
|
||||
|=======================
|
||||
|
||||
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.
|
||||
|
||||
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`.
|
||||
See {ref}/tls-ldap.html[Encrypting Communications Between {es} and LDAP].
|
||||
|
|
@ -73,6 +73,7 @@ user API.
|
|||
. Choose which types of realms you want to use to authenticate users.
|
||||
** <<configuring-ad-realm,Configure an Active Directory realm>>.
|
||||
** <<configuring-file-realm,Configure a file realm>>.
|
||||
** <<configuring-ldap-realm,Configure an LDAP realm>>.
|
||||
** <<configuring-native-realm,Configure a native realm>>.
|
||||
** <<configuring-pki-realm,Configure a PKI realm>>.
|
||||
|
||||
|
|
@ -136,6 +137,7 @@ include::securing-communications/enabling-cipher-suites.asciidoc[]
|
|||
include::securing-communications/separating-node-client-traffic.asciidoc[]
|
||||
include::authentication/configuring-active-directory-realm.asciidoc[]
|
||||
include::authentication/configuring-file-realm.asciidoc[]
|
||||
include::authentication/configuring-ldap-realm.asciidoc[]
|
||||
include::authentication/configuring-native-realm.asciidoc[]
|
||||
include::authentication/configuring-pki-realm.asciidoc[]
|
||||
include::{xes-repo-dir}/settings/security-settings.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
[role="xpack"]
|
||||
[[configuring-tls]]
|
||||
=== Encrypting Communications in {es}
|
||||
=== Encrypting communications in {es}
|
||||
|
||||
{security} enables you to encrypt traffic to, from, and within your {es} cluster.
|
||||
Connections are secured using Transport Layer Security (TLS/SSL).
|
||||
|
|
@ -23,6 +23,9 @@ information, see <<security-settings>>.
|
|||
. If you are using Active Directory user authentication,
|
||||
<<tls-active-directory,encrypt communications between {es} and your Active Directory server>>.
|
||||
|
||||
. If you are using LDAP user authentication,
|
||||
<<tls-ldap,encrypt communications between {es} and your LDAP server>>.
|
||||
|
||||
For more information about encrypting communications across the Elastic Stack,
|
||||
see {xpack-ref}/encrypting-communications.html[Encrypting Communications].
|
||||
|
||||
|
|
@ -30,3 +33,4 @@ include::node-certificates.asciidoc[]
|
|||
include::tls-transport.asciidoc[]
|
||||
include::tls-http.asciidoc[]
|
||||
include::tls-ad.asciidoc[]
|
||||
include::tls-ldap.asciidoc[]
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
[role="xpack"]
|
||||
[[tls-ldap]]
|
||||
==== Encrypting communications between {es} and LDAP
|
||||
|
||||
To protect the user credentials that are sent for authentication in an LDAP
|
||||
realm, it's highly recommended to encrypt communications between {es} 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. Clients and nodes that connect via
|
||||
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, see <<configuring-ldap-realm>>.
|
||||
|
||||
. Configure the realm's TLS 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 certificate must be a PEM encoded.
|
||||
|
||||
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 {es}.
|
||||
|
||||
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`.
|
||||
Loading…
Reference in New Issue