WARNING: Version 6.2 of the Elastic Stack has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« LDAP User Authentication PKI User Authentication »

› › ›

Active Directory User Authentication

edit

Active Directory User Authentication

edit

You can configure X-Pack security to communicate with Active Directory to authenticate users. To integrate with Active Directory, you configure an active_directory realm and map Active Directory users and groups to X-Pack security roles in the role mapping file.

To protect passwords, communications between Elasticsearch and the Active Directory server should be encrypted using SSL/TLS. Clients and nodes that connect via SSL/TLS to the Active Directory server need to have the Active Directory 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 Between Elasticsearch and Active Directory.

Configuring an Active Directory Realm

edit

X-Pack security uses LDAP to communicate with Active Directory, so active_directory realms are similar to ldap realms. Like LDAP directories, Active Directory stores users and groups hierarchically. The 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).

X-Pack security only supports Active Directory security groups. You cannot map distribution groups to roles.

When you use Active Directory for authentication, the username entered by the user is expected to match the sAMAccountName or userPrincipalName, not the common name.

The Active Directory realm authenticates users using an LDAP bind request. After authenticating the user, the realm then searches to find the user’s entry in Active Directory. Once the user has been found, the Active Directory realm then retrieves the user’s group memberships from the tokenGroups attribute on the user’s entry in Active Directory.

To configure an active_directory realm:

Add a realm configuration of type active_directory to elasticsearch.yml under the xpack.security.authc.realms namespace. At a minimum, you must set the realm type to active_directory and specify the Active Directory domain_name. To use SSL/TLS for secured communication with the Active Directory server, you must also set the url attribute and specify the ldaps protocol and secure port number. 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 Active Directory Realm Settings for all of the options you can set for an active_directory realm.

Binding to Active Directory fails if the domain name is not mapped in DNS. If DNS is not being provided by a Windows DNS server, add a mapping for the domain in the local /etc/hosts file.

For example, the following realm configuration configures X-Pack security to connect to ldaps://example.com:636 to authenticate users through Active Directory.
```
xpack:
  security:
    authc:
      realms:
        active_directory:
          type: active_directory
          order: 0 
          domain_name: ad.example.com
          url: ldaps://ad.example.com:636 
```
The realm order controls the order in which the configured realms are checked when authenticating a user.

If you don’t specify the URL, it defaults to ldap:<domain_name>:389.

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.

Configuring a Bind User

edit

By default, all of the LDAP operations are run by the user that X-Pack security is authenticating. In some cases, regular users may not be able to access all of the necessary items within Active Directory and a bind user is needed. A bind user can be configured and will be used to perform all operations other than the LDAP bind request, which is required to authenticate the credentials provided by the user.

The use of a bind user enables the run as feature to be used with the Active Directory realm and the ability to maintain a set of pooled connections to Active Directory. These pooled connection reduce the number of resources that must be created and destroyed with every user authentication.

The following example shows the configuration of a bind user through the user of the bind_dn and bind_password settings.

xpack:
  security:
    authc:
      realms:
        active_directory:
          type: active_directory
          order: 0
          domain_name: ad.example.com
          url: ldaps://ad.example.com:636
          bind_dn: es_svc_user@ad.example.com 
          bind_password: es_svc_user_password

This is the user that all Active Directory search requests are executed as. Without a bind user configured, all requests run as the user that is authenticating with Elasticsearch.

When a bind user is configured, connection pooling is enabled by default. Connection pooling can be disabled using the user_search.pool.enabled setting.

Multiple Domain Support

edit

When authenticating users across multiple domains in a forest, there are a few minor differences in the configuration and the way that users will authenticate. The domain_name setting should be set to the forest root domain name. The url setting also needs to be set as you will need to authenticate against the Global Catalog, which uses a different port and may not be running on every Domain Controller.

For example, the following realm configuration configures X-Pack security to connect to specific Domain Controllers on the Global Catalog port with the domain name set to the forest root.

xpack:
  security:
    authc:
      realms:
        active_directory:
          type: active_directory
          order: 0
          domain_name: example.com 
          url: ldaps://dc1.ad.example.com:3269, ldaps://dc2.ad.example.com:3269 
          load_balance:
            type: "round_robin"

	The `domain_name` is set to the name of the root domain in the forest.
	The `url` value used in this example has URLs for two different Domain Controllers, which are also Global Catalog servers. Port 3268 is the default port for unencrypted communication with the Global Catalog; port 3269 is the default port for SSL connections. The servers that are being connected to can be in any domain of the forest as long as they are also Global Catalog servers.
	A load balancing setting is provided to indicate the desired behavior when choosing the server to connect to.

In this configuration, users will need to use either their full User Principal Name (UPN) or their Down-Level Logon Name. A UPN is typically a concatenation of the username with @<DOMAIN_NAME such as johndoe@ad.example.com. The Down-Level Logon Name is the NetBIOS domain name, followed by a \ and the username, such as AD\johndoe. Use of Down-Level Logon Name requires a connection to the regular LDAP ports (389 or 636) in order to query the configuration container to retrieve the domain name from the NetBIOS name.

Load Balancing and Failover

edit

The load_balance.type setting can be used at the realm level to configure how X-Pack security should interact with multiple Active Directory servers. Two modes of operation are supported: failover and load balancing

Table 5. 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 Active Directory 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.

Active Directory Realm Settings

edit

Setting	Required	Description
`type`	yes	Indicates the realm type. Must be set to `active_directory`.
`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`.
`domain_name`	yes	Specifies the domain name of the Active Directory. X-Pack security uses the domain name to derive the LDAP URL and `user_search_dn` if those fields are not specified.
`url`	no/yes	Specifies an LDAP URL of the form `ldap[s]://<server>:<port>`. X-Pack security attempts to authenticate against this URL. If the URL is not specified, it is derived from the `domain_name`, assuming an unencrypted connection to port 389. For example, `ldap://<domain_name>:389`. This settings is required when connecting using SSL/TLS or via a custom port.
`bind_dn`	no	The DN of the user that is used to bind to Active Directory and perform searches. Due to its potential security impact, `bind_dn` is not exposed via the nodes info API.
`bind_password`	no	The password for the user that is used to bind to Active Directory. Due to its potential security impact, `bind_password` is not exposed via the nodes info API.
`load_balance.type`	no	The behavior to use when there are multiple LDAP URLs defined. For supported values see Load Balancing and Failover.
`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_search.base_dn`	no	Specifies the context to search for the user. Defaults to the root of the Active Directory domain.
`user_search.scope`	no	Specifies whether the user search should be `sub_tree` (default), `one_level`, or `base`. `sub_tree` searches all objects contained under `base_dn`. `one_level` only searches users directly contained within the `base_dn`. `base` specifies that the `base_dn` is a user object and that it is the only user considered.
`user_search.filter`	no	Specifies a filter to use to lookup a user given a username. The default filter looks up `user` objects with either `sAMAccountName` or `userPrincipalName`. If specified, this must be a valid LDAP user search filter, for example `(&(objectClass=user)(sAMAccountName={0}))`. For more information, see Search Filter Syntax.
`user_search.upn_filter`	no	Specifies a filter to use to lookup a user given a user principal name. The default filter looks up `user` objects with a matching `userPrincipalName`. If specified, this must be a valid LDAP user search filter, for example `(&(objectClass=user)(userPrincipalName={1}))`. `{1}` is the full user principal name provided by the user. For more information, see Search Filter Syntax.
`user_search.down_level_filter`	no	Specifies a filter to use to lookup a user given a down level logon name (DOMAIN\user). The default filter looks up `user` objects with a matching `sAMAccountName` in the domain provided. If specified, this must be a valid LDAP user search filter, for example `(&(objectClass=user)(sAMAccountName={0}))`. For more information, see Search Filter Syntax.
`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` when `bind_dn` is provided.
`user_search.pool.size`	no	Specifies the maximum number of connections to Active Directory server to allow in the connection pool. Defaults to `20`.
`user_search.pool.initial_size`	no	The initial number of connections to create to Active Directory 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 Active Directory 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	Specifies the distinguished name to retrieve as part of the health check. Defaults to the value of `bind_dn` if present, and if not falls back to `user_search.base_dn`.
`user_search.pool.health_check.interval`	no	How often to perform background checks of connections in the pool. Defaults to `60s`.
`group_search.base_dn`	no	Specifies the context to search for groups in which the user has membership. Defaults to the root of the Active Directory domain.
`group_search.scope`	no	Specifies whether the group search should be `sub_tree` (default), `one_level` or `base`. `sub_tree` searches all objects contained under `base_dn`. `one_level` searches for groups directly contained within the `base_dn`. `base` specifies that the `base_dn` is a group object and that it is the only group considered.
`unmapped_groups_as_roles`	no	Specifies whether the names of any unmapped Active Directory 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 role-mapping files (API based role-mappings are not considered). Defaults to `false`.
`files.role_mapping`	no	Specifies the path and file name of the YAML role mapping configuration file. Defaults to `ES_PATH_CONF/x-pack/role_mapping.yml`, where `ES_PATH_CONF` is `ES_HOME/config` (zip/tar installations) or `/etc/elasticsearch` (package installations).
`follow_referrals`	no	Specifies whether X-Pack security should follow referrals returned by the Active Directory server. Referrals are URLs returned by the server that are to be used to continue the LDAP operation (such as `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 Active Directory 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 Active Directory 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.truststore.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.truststore.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 an Active Directory 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 nodes info API. + Values are `none`, `certificate`, and `full`. Defaults to `full`. + See `xpack.ssl.verification_mode` for an explanation of these values.
`ssl.supported_protocols`	no	Specifies the supported protocols for TLS/SSL.
`ssl.cipher_suites`	no	Specifies the cipher suites that should be supported when communicating with the Active Directory 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 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 algorithms for the possible values. (Expert Setting).

Mapping Active Directory Users and Groups to Roles

edit

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 active_directory realm the users are managed externally in the Active Directory server, the expectation is that their roles are managed there as well. In fact, Active Directory supports the notion of groups, which often represent user roles for different systems in the organization.

The active_directory realm enables you to map Active Directory users to roles via their Active Directory groups, or other metadata. This role mapping can be configured via the role-mapping API, or by using a file stored on each node. When a user authenticates against an Active Directory realm, 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 Active Directory admins group to both the monitoring and user roles, maps the users group to the user role and maps the John Doe user to the user role.

Configured via the role-mapping API:

PUT _xpack/security/role_mapping/admins
{
  "roles" : [ "monitoring" , "user" ],
  "rules" : { "field" : {
    "groups" : "cn=admins,dc=example,dc=com" 
  } },
  "enabled": true
}

The Active Directory distinguished name (DN) of the admins group.

PUT _xpack/security/role_mapping/basic_users
{
  "roles" : [ "user" ],
  "rules" : { "any": [
    { "field" : {
      "groups" : "cn=users,dc=example,dc=com" 
    } },
    { "field" : {
      "dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" 
    } }
  ] },
  "enabled": true
}

	The Active Directory distinguished name (DN) of the `users` group.
	The Active Directory distinguished name (DN) of the user `John Doe`.

Or, alternatively, configured via the role-mapping file:

monitoring: 
  - "cn=admins,dc=example,dc=com" 
user:
  - "cn=users,dc=example,dc=com" 
  - "cn=admins,dc=example,dc=com"
  - "cn=John Doe,cn=contractors,dc=example,dc=com"

	The name of the role.
	The Active Directory distinguished name (DN) of the `admins` group.
	The Active Directory distinguished name (DN) of the `users` group.
	The Active Directory distinguished name (DN) of the user `John Doe`.

For more information, see Mapping Users and Groups to Roles.

User Metadata in Active Directory Realms

edit

When a user is authenticated via an Active Directory realm, the following properties are populated in the user’s metadata. This metadata is returned in the authenticate API, and can be used with 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 metadata can be extracted from the Active Directory server by configuring the metadata setting on the Active Directory realm.

Setting up SSL Between Elasticsearch and Active Directory

edit

To protect the user credentials that are sent for authentication, it’s highly recommended to encrypt communications between Elasticsearch and your Active Directory server. Connecting via SSL/TLS ensures that the identity of the Active Directory server is authenticated before X-Pack security transmits the user credentials, and the usernames and passwords are encrypted in transit.

To encrypt communications between Elasticsearch and Active Directory:

Configure each node to trust certificates signed by the CA that signed your Active Directory server certificates. The following example demonstrates how to trust a CA certificate, cacert.pem, located within the X-Pack configuration directory:

xpack:
  security:
    authc:
      realms:
        active_directory:
          type: active_directory
          order: 0
          domain_name: ad.example.com
          url: ldaps://ad.example.com:636
          ssl:
            certificate_authorities: [ "ES_PATH_CONF/x-pack/cacert.pem" ]

The CA cert must be a PEM encoded certificate.

Set the url attribute in the realm configuration to specify the LDAPS protocol and the secure port number. For example, url: ldaps://ad.example.com:636.
Restart Elasticsearch.

By default, when you configure X-Pack security to connect to Active Directory using SSL/TLS, X-Pack 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, X-Pack security does not allow a connection to the Active Directory 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.

« LDAP User Authentication PKI User Authentication »

	The realm order controls the order in which the configured realms are checked when authenticating a user.
	If you don’t specify the URL, it defaults to `ldap:<domain_name>:389`.