WARNING: Version 5.4 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.
Active Directory User Authentication
editActive Directory User Authentication
editYou 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
editX-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.
To configure an active_directory
realm:
-
Add a realm configuration of type
active_directory
toelasticsearch.yml
under thexpack.security.authc.realms
namespace. At a minimum, you must set the realmtype
toactive_directory
and specify the Active Directorydomain_name
. To use SSL/TLS for secured communication with the Active Directory server, you must also set theurl
attribute and specify theldaps
protocol and secure port number. If you are configuring multiple realms, you should also explicitly set theorder
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 anactive_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 unmapped_groups_as_roles: true
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 this option is enabled, Active Directory groups are automatically mapped to roles of the same name.
When you configure realms in
elasticsearch.yml
, only the realms you specify are used for authentication. If you also want to use thenative
orfile
realms, you must include them in the realm chain. - Restart Elasticsearch.
Multiple Domain Support
editWhen 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 |
|
The |
|
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
editThe 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 9. Load Balancing and Failover Types
Type |
Description |
||
|
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. |
||
|
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 |
||
|
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. |
||
|
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
editSetting |
Required |
Description |
|
yes |
Indicates the realm type. Must be set to |
|
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 |
|
no |
Indicates whether this realm is enabled or disabled. Enables
you to disable a realm without removing its configuration.
Defaults to |
|
yes |
Specifies the domain name of the Active Directory. X-Pack security
uses the domain name to derive the LDAP URL and |
|
no/yes |
Specifies an LDAP URL of the form |
|
no |
The behavior to use when there are multiple LDAP URLs defined. For supported values see Load Balancing and Failover. |
|
no |
When using |
|
no |
Specifies the context to search for the user. Defaults to the root of the Active Directory domain. |
|
no |
Specifies whether the user search should be |
|
no |
Specifies a filter to use to lookup a user given a username.
The default filter looks up |
|
no |
Specifies a filter to use to lookup a user given a user principal name.
The default filter looks up |
|
no |
Specifies a filter to use to lookup a user given a down level logon name (DOMAIN\user).
The default filter looks up |
|
no |
Specifies the context to search for groups in which the user has membership. Defaults to the root of the Active Directory domain. |
|
no |
Specifies whether the group search should be |
|
no |
Specifies whether the names of any unmapped Active Directory
groups should be used as role names and assigned to the user.
Defaults to |
|
no |
Specifies the path and file name of the
YAML role mapping configuration file.
Defaults to |
|
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 |
|
no |
Specifies the path to the PEM encoded private key to use if the Active Directory
server requires client authentication. |
|
no |
Specifies the passphrase to decrypt the PEM encoded private key if it is encrypted. |
|
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. |
|
no |
Specifies the paths to the PEM encoded certificate authority certificates that
should be trusted. |
|
no |
The path to the Java Keystore file that contains a private key and certificate. |
|
no |
The password to the keystore. |
|
no |
The password for the key in the keystore. Defaults to the keystore password. |
|
no |
The path to the Java Keystore file that contains the certificates to trust.
|
|
no |
The password to the truststore. |
|
no |
Specifies the type of verification to be performed when
connecting to an Active Directory server using |
|
no |
Specifies the supported protocols for TLS/SSL. |
|
no |
Specifies the cipher suites that should be supported when communicating with the Active Directory server. |
|
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 |
|
no |
Specifies the maximum number of user entries that can be stored in the cache at one time. Defaults to 100,000. |
|
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
editAn 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 and groups
to roles in the role mapping file stored on each node. You specify users and
groups using their distinguished names (DNs). 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.
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 |
|
The Active Directory distinguished name (DN) of the |
|
The Active Directory distinguished name (DN) of the user |
For more information, see Mapping Users and Groups to Roles.
User Metadata in Active Directory Realms
editWhen a user is authenticated via an Active Directory realm, the following properties are populated in user’s metadata. This metadata is returned in the authenticate API, and can be used with templated queries in roles.
Field |
Description |
|
The distinguished name of the user. |
|
The distinguished name of each of the groups that were resolved for the user (regardless of whether those groups were mapped to a role). |
Setting up SSL Between Elasticsearch and Active Directory
editTo 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: [ "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.
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 none
.