OpenSearch/docs/en/security/authentication/active-directory-realm.asciidoc

[[active-directory-realm]]
=== Active Directory User Authentication

You can configure {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 {security} roles in the
<<mapping-roles, 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
<<active-directory-ssl>>.

==== Configuring an Active Directory Realm

{security} uses LDAP to communicate with Active Directory, so `active_directory`
realms are similar to <<ldap-realm, `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).

{security} only supports Active Directory security groups. You cannot map
distribution groups to roles.

NOTE: 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.

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 <<ad-settings, Active Directory Realm Settings>>
for all of the options you can set for an `active_directory` realm.
+
NOTE: 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 {security} to connect
to `ldaps://example.com:636` to authenticate users through Active Directory.
+
[source, yaml]
------------------------------------------------------------
xpack:
  security:
    authc:
      realms:
        active_directory:
          type: active_directory
          order: 0 <1>
          domain_name: ad.example.com
          url: ldaps://ad.example.com:636 <2>
          unmapped_groups_as_roles: true <3>
------------------------------------------------------------
<1> The realm order controls the order in which the configured realms are checked
    when authenticating a user.
<2> If you don't specify the URL, it defaults to `ldap:<domain_name>:389`.
<3> When this option is enabled, Active Directory groups are automatically mapped
    to roles of the same name.
+
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.

===== Multiple Domain Support
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 {security} to connect to specific
Domain Controllers on the Global Catalog port with the domain name set to the forest root.

[source, yaml]
------------------------------------------------------------
xpack:
  security:
    authc:
      realms:
        active_directory:
          type: active_directory
          order: 0
          domain_name: example.com <1>
          url: ldaps://dc1.ad.example.com:3269, ldaps://dc2.ad.example.com:3269 <2>
          load_balance:
            type: "round_robin" <3>
------------------------------------------------------------
<1> The `domain_name` is set to the name of the root domain in the forest.
<2> 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.
<3> 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.

[[ad-load-balancing]]
===== Load Balancing and Failover
The `load_balance.type` setting can be used at the realm level to configure how
{security} should interact with multiple Active Directory servers. Two modes of
operation are supported: failover and load balancing

.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.
|=======================

[[ad-settings]]
===== Active Directory Realm Settings

[cols="4,^3,10"]
|=======================
| 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. {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>`.
                                          {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.
| `load_balance.type`        | no       | The behavior to use when there are multiple LDAP URLs defined.
                                          For supported values see <<ad-load-balancing>>.
| `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 https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[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 either
                                          a matching `userPrincipalName` or a `sAMAccountName` matching the account
                                          portion of the user principal name. If specified, this
                                          must be a valid LDAP user search filter, for example
                                          `(&(objectClass=user)(sAMAccountName={0}))`. `{0}` is the value
                                          preceding the `@` sign in the user principal name and `{1}` is
                                          the full user principal name provided by the user. For more
                                          information, see https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[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 https://msdn.microsoft.com/en-us/library/aa746475(v=vs.85).aspx[Search Filter Syntax].
| `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 <<mapping-roles-file, 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
                                          <<ldap-role-mapping, YAML role  mapping configuration file>>.
                                          Defaults to `CONF_DIR/x-pack/role_mapping.yml`,
                                          where `CONF_DIR` is `ES_HOME/config` (zip/tar installations)
                                          or `/etc/elasticsearch` (package installations).
| `follow_referrals`         | no       | Specifies whether {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.trustsore.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.trustsore.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
                                          {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
                                          Values are `none`, `certificate`, and `full`. Defaults to `full`.
| `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
                                          {ref}/common-options.html#time-units[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-algo, Cache hash algorithms>> for the
                                          possible values. (Expert Setting).
|=======================

[[mapping-roles-ad]]
==== Mapping Active Directory Users and 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
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 {ref}/security-api-role-mapping.html[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:
[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 Active Directory distinguished name (DN) of the `admins` group.

[source,js]
--------------------------------------------------
PUT _xpack/security/role_mapping/basic_users
{
  "roles" : [ "user" ],
  "rules" : { "any": [
    { "field" : {
      "groups" : "cn=users,dc=example,dc=com" <1>
    } },
    { "field" : {
      "dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" <2>
    } }
  ] },
  "enabled": true
}
--------------------------------------------------
// CONSOLE
<1> The Active Directory distinguished name (DN) of the `users` group.
<2> The Active Directory distinguished name (DN) of the user `John Doe`.

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"
  - "cn=John Doe,cn=contractors,dc=example,dc=com" <4>
------------------------------------------------------------
<1> The name of the role.
<2> The Active Directory distinguished name (DN) of the `admins` group.
<3> The Active Directory distinguished name (DN) of the `users` group.
<4> The Active Directory distinguished name (DN) of the user `John Doe`.

For more information, see <<mapping-roles, Mapping Users and Groups to Roles>>.

[[ad-user-metadata]]
==== User Metadata in Active Directory Realms
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
{ref}/security-api-authenticate.html[authenticate API], and can be used with
<<templating-role-query, 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.

[[active-directory-ssl]]
==== Setting up SSL Between Elasticsearch and Active Directory

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 {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 {xpack} configuration directory:
+
[source,shell]
--------------------------------------------------
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: [ "CONFIG_DIR/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.

NOTE: By default, when you configure {security} to connect to Active Directory
      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
      Active Directory server. This is done to protect against man-in-the-middle
      attacks. If necessary, you can disable this behavior by setting the
      {ref}/security-settings.html#ssl-tls-settings[`ssl.verification_mode`] property to `none`.