Active Directory Authentication

The Active Directory Realm uses LDAP to communicate with Active Directory. The Active Directory Realm is similar to the LDAP realm but takes advantage of extra features and streamlines configuration.

A general overview of LDAP will help with the configuration. LDAP databases, like Active Directory, store 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 Active Directory 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.

Like all realms, the active_directory 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 Active Directory Configuration.

shield:
  authc:
    realms:
      active_directory:
        type: active_directory
        order: 0
        domain_name: example.com
        unmapped_groups_as_roles: true
      ...

Active Directory authentication expects the username entered to be the same name as the sAMAccountName or userPrincipalName and not the CommonName (CN). The URL is optional, but allows the use of custom ports.

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.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 Active Directory 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 node. Tools like Puppet or Chef can help with this.

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

To do this, first obtain a certificate for the Active Directory servers or a CA certificate that has signed the 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

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 Active Directory server. This behavior can be disabled by setting the hostname_verification property.

Finally, restart Elasticsearch to pick up the changes to elasticsearch.yml.

To avoid connecting to the Active Directory 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:

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

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

$ curl -XPOST 'http://localhost:9200/_shield/realm/ad1,ad2/_cache/clear'