LDAP User Authentication
editLDAP User Authentication
editYou can configure Shield to communicate with a Lightweight Directory Access Protocol (LDAP) directory to authenticate users. To integrate with LDAP, you configure an LDAP realm and assign LDAP groups to Shield roles in the role mapping file.
To protect passwords, communications between Shield 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 Setting Up SSL.
Configuring an LDAP Realm
editLDAP 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 space is ignored.
The LDAP realm supports two modes of operation, a user search mode and a mode with specific templates for user DNs. See LDAP Realm Settings for all of the options you can set for an LDAP realm.
Configuring an LDAP Realm with User Search [1.1.0] Added in 1.1.0.
editLDAP 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 user DN based on the username and an LDAP attribute.
To configure an LDAP Realm with User Search:
-
Add a realm configuration of type
ldap
toelasticsearch.yml
in theshield.authc.realms
namespace. At a minimum, you must set the realmtype
toldap
, specify theurl
of the LDAP server, and specify the container DN to search for users with theuser_search.base_dn
option. If you are configuring multiple realms, you should also explicitly set theorder
attribute to control the order in which the realms are consulted during authentication. See 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:
shield: 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: changeme user_search: base_dn: "dc=example,dc=com" attribute: cn group_search: base_dn: "dc=example,dc=com" files: role_mapping: "CONFIG_DIR/shield/role_mapping.yml" unmapped_groups_as_roles: false
When you configure realms in
elasticsearch.yml
, only the realms you specify are used for authentication. If you also want to use thenative
orfile
realms, you must include them in the realm chain. - Restart Elasticsearch
Configuring an LDAP Realm with User DN Templates
editIf 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
toelasticsearch.yml
in theshield.authc.realms
namespace. At a minimum, you must set the realmtype
toldap
, specify theurl
of the LDAP server, and specify at least one template with theuser_dn_templates
option. If you are configuring multiple realms, you should also explicitly set theorder
attribute to control the order in which the realms are consulted during authentication. See 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:
shield: 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
LDAP Load Balancing and Failover [2.3.0] Added in 2.3.0.
editThe load_balance.type
setting can be used at the realm level to configure how Shield should interact with multiple LDAP
servers. Shield supports both failover and load balancing modes of operation.
Table 1. Load Balancing and Failover Types
Type |
Description |
|
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. |
|
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 |
|
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. |
|
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 Realm Settings
editTable 2. Common LDAP Realm Settings
Setting |
Required |
Description |
|
yes |
Indicates the realm type. Must be set to |
|
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 |
|
no |
Indicates whether this realm is enabled or disabled.
Enables you to disable a realm without removing its
configuration. Defaults to |
|
yes |
Specifies one or more LDAP URLs of the form of
|
|
no |
The behavior to use when there are multiple LDAP URLs defined. For supported values see LDAP load balancing and failover types. |
|
no |
When using |
|
no |
Specifies the attribute to examine on the user for group
membership. The default is |
|
no |
Specifies a container DN to search for groups in which
the user has membership. When this element is absent,
Shield searches for the attribute specified by
|
|
no |
Specifies whether the group search should be
|
|
no |
Specifies a filter to use to lookup a group. If not
set, the realm searches for |
|
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. |
|
no |
Specifies whether the names of any unmapped LDAP groups
should be used as role names and assigned to the user.
Defaults to |
|
no |
Specifies the TCP connect timeout period for establishing an
LDAP connection. An |
|
no |
Specifies the TCP read timeout period after establishing an LDAP connection.
An |
|
no |
Specifies the LDAP Server enforced timeout period for an LDAP search.
An |
|
no |
Specifies the path and file name for the
YAML role mapping configuration
file. Defaults to
|
|
no |
Specifies whether Shield 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
|
|
no |
Specifies whether hostname verification is performed when
connecting to an LDAP server. When |
|
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
time units.
Defaults to |
|
no |
Specifies the maximum number of user entries that can be stored in the cache at one time. Defaults to 100,000. |
|
no |
Specifies the hashing algorithm that is used for the cached user credentials. See Cache hash algorithms for the possible values. (Expert Setting) |
Table 3. User Template LDAP Realm Settings
Setting |
Required |
Description |
|
yes |
Specifies the DN template that replaces the user name
with the string |
Table 4. User Search LDAP Realm Settings [1.1.0] Added in 1.1.0.
Setting |
Required |
Description |
|
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, |
|
no |
The password for the user that is used
to bind to the LDAP. Due to its potential
security impact, |
|
yes |
Specifies a container DN to search for users. |
|
no |
The scope of the user search. Valid values
are |
|
no |
Specifies the attribute to match with the
username presented to Shield. Defaults to
|
|
no |
Specifies the maximum number of connections
to the LDAP server to allow in the connection
pool. Defaults to |
|
no |
The initial number of connections to create
to the LDAP server on startup. Defaults to |
|
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 |
|
no |
Specifies the distinguished name to retrieve
as part of the health check. Defaults to the
value of |
|
no |
How often to perform background checks
of connections in the pool. Defaults to
|
If any settings starting with user_search
are specified, the user_dn_templates
the settings are ignored.
Assigning LDAP Groups to Roles
editTo configure privileges for LDAP users, you assign LDAP groups to roles in the role mapping 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 assigned to the set of groups that the user belongs to.
You specify groups using their distinguished names. For example, the following mapping
configuration assigns the LDAP admins
group both the monitoring
and user
roles, and
assigns the user
role to the users
group.
monitoring: - "cn=admins,dc=example,dc=com" user: - "cn=users,dc=example,dc=com" - "cn=admins,dc=example,dc=com"
The name of a role defined in |
|
The distinguished name of the |
|
The distinguished name of the |
For more information, see Mapping Users and Groups to Roles.
Encrypting Communications Between Shield and LDAP with SSL/TLS
editYou should encrypt communications between Shield and your LDAP server to protect the user credentials that are sent to for authentication. Connecting via SSL/TLS ensures that the identity of the LDAP server is authenticated before Shield transmits the user credentials, and the user names and passwords are encrypted in transit.
To encrypt communications between Shield and your LDAP server:
-
Configure each node to trust certificates signed by the CA that signed your LDAP server certificates. For example, the following command imports
cacert.pem
into node01’s keystore. (For information about using truststores, see Configuring a Separate Truststore.)cd CONFIG_DIR/shield keytool -importcert -keystore node01.jks -file cacert.pem -alias ldap_ca
The CA cert must be a PEM encoded certificate.
You can also import the individual server certificates rather than the CA certificate, but this is only recommended if you have a single LDAP server. You can fetch the LDAP server certificate with
openssl
. For example, the following command gets the certificate forldap.example.com
and stores it locally inldap.crt
.echo | openssl s_client -connect ldap.example.com:636 2>/dev/null | openssl x509 > ldap.crt
If you are using an older version of openssl you might need to use use the
-host
and-port
options rather than the-connect
option. -
If you haven’t already configured the path to the node’s keystore or truststore in
elasticsearch.yml
, set theshield.ssl.keystore.path
orshield.ssl.truststore.path
attributes. For example:shield.ssl.keystore.path: /home/es/config/shield/node01.jks shield.ssl.keystore.password: myPass shield.ssl.keystore.key_password: myKeyPass
The full path to the node keystore file. This must be a location within the Elasticsearch configuration directory.
The password used to access the keystore.
The password used to access the certificate. This is only required if you specified a separate certificate password when generating the certificate.
For more information, see Enabling SSL/TLS in the Node Configuration.
-
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 to pick up the changes to
elasticsearch.yml
.
By default, when you configure Shield to connect to an LDAP server using SSL/TLS,
Shield 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, Shield 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 hostname_verification
property to false
. hostname_verification
is considered to be a sensitive setting and
is not exposed via nodes info API.