Active Directory user authentication

ECE ECK Elastic Cloud Hosted Self Managed

You can configure Elastic Stack security features to communicate with Active Directory to authenticate users.

The security features use 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 component (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).

The security features supports only Active Directory security groups. You can't map distribution groups to roles.

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. After 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 integrate with Active Directory, you configure an active_directory realm and map Active Directory groups to user roles in Elasticsearch.

1. Add a realm configuration of type active_directory to elasticsearch.yml under the xpack.security.authc.realms.active_directory namespace. At a minimum, you must specify the Active Directory domain_name and order.

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

   In a self-managed cluster, if DNS is not being provided by a Windows DNS server, you can add a mapping for the domain in the local /etc/hosts file.

xpack:
  security:
    authc:
      realms:
        active_directory:
          my_ad:  
            order: 0 1
            domain_name: ad.example.com 2
            url: ldaps://ad.example.com:636 3

xpack:
  security:
    authc:
      realms:
        active_directory:
          my_ad:
            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

2. (Optional) Configure how Elasticsearch should interact with multiple Active Directory servers.

   The load_balance.type setting can be used at the realm level. Two modes of operation are supported: failover and load balancing. See Active Directory realm settings.

3. (Optional) To protect passwords, encrypt communications between Elasticsearch and the Active Directory server.

   • For self-managed clusters and Elastic Cloud on Kubernetes deployments, clients and nodes that connect using 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 trust store.

   • For Elastic Cloud Enterprise and Elastic Cloud Hosted deployments, if your Domain Controller is configured to use LDAP over TLS and it uses a self-signed certificate or a certificate that is signed by your organization’s CA, you need to enable the deployment to trust this certificate.

4. Restart Elasticsearch.

You can choose to configure an Active Directory realm using a bind user.

The Active Directory realm authenticates users using an LDAP bind request. By default, all of the LDAP operations are run by the user that Elasticsearch 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 is used to perform all operations other than the LDAP bind request, which is required to authenticate the credentials provided by the user.

When you specify a bind_dn, this specific user is used to search for the Distinguished Name (DN) of the authenticating user based on the provided username and an LDAP attribute. If found, this user is authenticated by attempting to bind to the LDAP server using the found DN and the provided password.

The use of a bind user enables the run as feature to be used with the Active Directory realm.

In self-managed clusters, use of a bind user also enables the ability to maintain a set of pooled connections to Active Directory. These pooled connections reduce the number of resources that must be created and destroyed with every user authentication.

To configure a bind user:

1. Add your user settings for the active_directory realm as follows:

   Important

   In Elastic Cloud Enterprise, you must apply the user settings to each deployment template.

   xpack:
     security:
       authc:
         realms:
           active_directory:
             my_ad:
               order: 2 
               domain_name: ad.example.com 
               url: ldap://ad.example.com:389 
               bind_dn: es_svc_user@ad.example.com 1
   

   1. The user to run as for all Active Directory search requests.

2. Configure the password for the bind_dn user by adding the appropriate xpack.security.authc.realms.active_directory.<my_ad>.secure_bind_password setting to the Elasticsearch keystore.

   In self-managed deployments, when a bind user is configured, connection pooling is enabled by default. Connection pooling can be disabled using the user_search.pool.enabled setting.

   Warning

   In Elastic Cloud Hosted and Elastic Cloud Enterprise, after you configure secure_bind_password, any attempt to restart the deployment will fail until you complete the rest of the configuration steps. If you want to rollback the Active Directory realm configurations, you need to remove the xpack.security.authc.realms.active_directory.<my_ad>.secure_bind_password that was just added.

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.

Because users are managed externally in the Active Directory server, the expectation is that their roles are managed there as well. Active Directory groups often represent user roles for different systems in the organization.

The active_directory realm enables you to map Active Directory users to roles using their Active Directory groups or other metadata.

You can map Active Directory groups to roles for your users in the following ways:

• Using the role mappings page in Kibana.
• Using the role mapping API.
• Using a role mapping file.

For more information, see Mapping users and groups to roles.

 POST /_security/role_mapping/ldap-superuser {
"enabled": true,
"roles": [ "superuser" ], 1
"rules": {
"all" : [
{ "field": { "realm.name": "my_ad" } }, 2
{ "field": { "groups": "cn=administrators, dc=example, dc=com" } } 3
    ]
},
"metadata": { "version": 1 }
}

1. The name of the role we want to assign, in this case superuser.
2. The name of our active_directory realm.
3. The Distinguished Name of the Active Directory group whose members should get the superuser role in the deployment.

superuser:
- cn=Senior Manager, cn=management, dc=example, dc=com
- cn=Senior Admin, cn=management, dc=example, dc=com

Referencing the file in elasticsearch.yml:

xpack:
  security:
    authc:
      realms:
        active_directory:
          my_ad:
            order: 2
            domain_name: ad.example.com
            url: ldaps://ad.example.com:636
            bind_dn: es_svc_user@ad.example.com
            ssl:
              certificate_authorities: ["/app/config/cacerts/ca.crt"]
              verification_mode: certificate
            files:
              role_mapping: "/app/config/mappings/role-mappings.yml"

When a user is authenticated using 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.

Additional metadata can be extracted from the Active Directory server by configuring the metadata setting on the Active Directory realm.

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

See Load balancing and failover.

To protect the user credentials that are sent for authentication, you should encrypt communications between Elasticsearch and your Active Directory server. Connecting using SSL/TLS ensures that the identity of the Active Directory server is authenticated before Elasticsearch transmits the user credentials and the usernames and passwords are encrypted in transit.

Clients and nodes that connect using 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 trust store.

If you're using Elastic Cloud Hosted or Elastic Cloud Enterprise, then you must upload your certificate as a custom bundle before it can be referenced.

If you're using Elastic Cloud on Kubernetes, then install the certificate as a custom configuration file.

xpack.security.authc.realms.active_directory.my_ad.ssl.truststore.path:
"/app/config/truststore/ca.p12"

The following example demonstrates how to trust a CA certificate (cacert.pem), which is located within the configuration directory.

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

For more information about these settings, see Active Directory realm settings.

The Active Directory security realm uses the Kibana-provided basic authentication login form. Basic authentication is enabled by default.