LDAP Authentication | Shield - Elasticsearch Security Plugin [1.0]

From version 5.0 onward, Shield is part of X-Pack. For more information, see Securing the Elastic Stack.

› ›

« esusers - Internal File Based Authentication Active Directory Authentication »

LDAP Authenticationedit

A secure Elasticsearch cluster can authenticate users from a Lightweight Directory Access Protocol (LDAP) directory. With LDAP Authentication, you can assign roles to LDAP groups. 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.

This section discusses configuration for an LDAP Realm.

LDAP Overviewedit

LDAP stores users and groups hierarchically, similar to the way folders are grouped in a file system. The path to any entry is a Distinguished Name, or DN. A DN uniquely identifies a user or group. User and group names typically use attributes such as common name (cn) or unique ID (uid). An LDAP directory’s hierarchy is built from containers such as the organizational unit (ou), organization (o), or domain controller (dc).

LDAP ignores white space in a DN definition. The following two DNs are equivalent:

"cn=admin,dc=example,dc=com"
"cn =admin ,dc= example , dc = com"

Although optional, connections to the LDAP server should use the Secure Sockets Layer (SSL/TLS) protocol to protect passwords. Clients and nodes that connect via SSL/TLS to the LDAP server require the certificate or the root CA for the server. These certificates should be put into each node’s keystore/truststore.

LDAP Realm Settingsedit

Like all realms, the ldap realm is configured under the shield.authc.realms settings namespace in the elasticsearch.yml file. The following snippet shows an example of such configuration:

Example LDAP Realm Configuration.

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

Table 3. LDAP Realm Settings

Setting	Required	Description
`type`	yes	Indicates the realm type and must be set to `ldap`.
`order`	no	Indicates the priority of this realm within the realm chain. Realms with lower order will be consulted first. Although not required, it is highly recommended to explicitly set this value when multiple realms are configured. Defaults to `Integer.MAX_VALUE`.
`enabled`	no	Indicates whether this realm is enabled/disabled. Provides an easy way to disable realms in the chain without removing their configuration. Defaults to `true`.
`url`	yes	Specifies the LDAP URL in the form of `ldap[s]://<server>:<port>`. Shield attempts to authenticate against this URL.
`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.
`group_search.base_dn`	no	Specifies a container DN to search for groups in which the user has membership. When this element and all other elements beginning with `group_search` are absent, Shield searches for a `memberOf` attribute set on the user in order to determine group membership. If any of the `group_search` settings are set, this value must be provided.
`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	When not set, the realm will search for `group`, `groupOfNames`, or groupOfUniqueNames', with the attributes `member or `memberOf`. Any instance of `{0}` in the filter will be replaced by the user attribute defined in `group_search.user_attribute`
`group_search.user_attribute`	no	Specifies the user attribute that will be fetched and provided as a parameter to the filter. If not set, the user DN is passed into the filter.
`unmapped_groups_as_roles`	no	When set to `true`, the names of any unmapped LDAP groups are used as role names and assigned to the user. The default value is `false`.
`connect_timeout`	no	The timeout period for establishing an LDAP connection. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to "5s" - for 5 seconds
`read_timeout`	no	The timeout period for an LDAP operation. An `s` at the end indicates seconds, or `ms` indicates milliseconds. Defaults to "5s" - for 5 seconds
`files.role_mapping`	no	Specifies the path and file name for the YAML role mapping configuration file. The default file name is `role_mapping.yml` in the Shield config directory.
`hostname_verification`	no	When set to `true`, hostname verification will be performed when connecting to a LDAP server. 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. Defaults to `true`.
`cache.ttl`	no	Specified the time-to-live for cached user entries (a user and its credentials will be cached for this configured period of time). Defaults to `20m` (use the standard elasticsearch time units).
`cache.max_users`	no	Specified the maximum number of user entries that can live in the cache at a given time. Defaults to 100,000.
`cache.hash_algo`	no	(Expert Setting) Specifies the hashing algorithm that will be used for the in-memory cached user credentials (see here for possible values).

hostname_verification is considered to be a senstivie setting and therefore are not exposed via nodes info API.

Mapping Groups to Rolesedit

By default, the mapping file that connects groups and roles is config/shield/role_mapping.yml. You can configure the path and name of the mapping file by setting the appropriate value for the shield.authc.ldap.files.role_mapping or shield.authc.active_directory.files.role_mapping configuration parameter. When you map roles to groups, the roles of a user in that group are the combination of the roles assigned to that group and the roles assigned to that user.

The role_mapping.yml file uses the YAML format. Within a mapping file, Elasticsearch roles are keys and LDAP groups are values. Groups and roles can have a many-to-many mapping.

Example Group and Role Mapping File.

# Example LDAP group mapping configuration:
# roleA   this is an elasticsearch role
#  - groupA-DN  this is any group distinguished name
#  - groupB-DN
monitoring:
  - "cn=admins,dc=example,dc=com"
user:
  - "cn=users,dc=example,dc=com"
  - "cn=admins,dc=example,dc=com"

After setting up group-to-role mappings, copy this file to each node. Tools like Puppet or Chef can help with this.

Adding an LDAP server certificateedit

To use SSL/TLS to access your LDAP server over an URL with the ldaps protocol, make sure the LDAP client used by Shield can access the certificate of the CA that signed the LDAP server’s certificate. This enables Shield’s LDAP client to authenticate the LDAP server before sending any passwords to it.

To do this, first obtain a certificate for the LDAP servers or a CA certificate that has signed the LDAP certificate. You can use the openssl command to fetch the certificate and add the certificate to the ldap.crt file, as in the following Unix example:

echo | openssl s_client -connect ldap.example.com:636 2>/dev/null | openssl x509 > ldap.crt

Older versions of openssl might not have the -connect option. Instead use the -host and -port options.

This certificate needs to be stored in the node keystore/truststore. Import the certificate into the truststore with the following command, providing the password for the keystore when prompted.

keytool -import -keystore node01.jks -file ldap.crt

If not already configured, add the path of the keystore/truststore to elasticsearch.yml as described in Securing Nodes. By default, Shield will attempt to verify the hostname or IP address used in the url with the values in the certificate. If the values in the certificate do not match, Shield will not allow a connection to the LDAP server. This behavior can be disabled by setting the hostname_verification property.

Restart Elasticsearch to pick up the changes to elasticsearch.yml.

User Cacheedit

To avoid connecting to the LDAP server for every incoming request, the users and their credentials are cached locally on each node. This is a common practice when authenticating against remote servers and as can be seen in the table above, the characteristics of this cache are configurable.

The cached user credentials are hashed in memory, and there are several hash algorithms to choose from:

Table 4. Cache hash algorithms

Algorithm	Description
`bcrypt`	Uses `bcrypt` algorithm with salt generated in 10 rounds.
`bcrypt4`	Uses `bcrypt` algorithm with salt generated in 4 rounds (default).
`bcrypt5`	Uses `bcrypt` algorithm with salt generated in 5 rounds.
`bcrypt6`	Uses `bcrypt` algorithm with salt generated in 6 rounds.
`bcrypt7`	Uses `bcrypt` algorithm with salt generated in 7 rounds.
`bcrypt8`	Uses `bcrypt` algorithm with salt generated in 8 rounds.
`bcrypt9`	Uses `bcrypt` algorithm with salt generated in 9 rounds.
`sha1`	Uses `SHA1` algorithm.
`sha2`	Uses `SHA2` algorithm.
`md5`	Uses `MD5` algorithm.
`noop`,`clear_text`	Doesn’t hash the credentials and keeps it in clear text in memory. CAUTION: keeping clear text is considered insecure and can be compromised at the OS level (e.g. memory dumps and `ptrace`).

Cache Eviction APIedit

Shield exposes an API to force cached user eviction. The following example, evicts all users from the ldap1 realm:

$ curl -XPOST 'http://localhost:9200/_shield/realm/ldap1/_cache/clear'

It is also possible to evict specific users:

$ curl -XPOST 'http://localhost:9200/_shield/realm/ldap1/_cache/clear?usernames=rdeniro,alpacino'

Multiple realms can also be specified using comma-delimited list:

$ curl -XPOST 'http://localhost:9200/_shield/realm/ldap1,ldap2/_cache/clear'

« esusers - Internal File Based Authentication Active Directory Authentication »