Active Directory User Authentication
editActive Directory User Authentication
editYou can configure Shield to communicate with Active Directory to authenticate users. To integrate with Active Directory, you configure an Active Directory realm and assign Active Directory users and groups to Shield roles in the role mapping file.
To protect passwords, communications between Shield and the LDAP server should be encrypted using SSL/TLS. Clients and nodes that connect via SSL/TLS to the LDAP server need to have the LDAP server’s certificate or the server’s root CA certificate installed in their keystore or truststore. For more information about installing certificates, see Encrypting Communications Between Shield and Active Directory with SSL/TLS.
Configuring an Active Directory Realm
editShield 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 space is ignored.
Shield 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
in theshield.authc.realms
namespace. At a minimum, you must set the realmtype
toactive_directory
and specify the Active Directorydomain_name
. To use SSL/TLS to encrypt communications with the Active Directory server, you must also set theurl
attribute and specify the LDAPS 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 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 Shield to connect to
ldaps://example.com:636
to authenticate users through Active Directory.shield: 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, Shield automatically maps Active Directory groups to roles of the same name defined in
roles.yml
. - Restart Elasticsearch.
LDAP Load Balancing and Failover [2.3.0] Added in 2.3.0.
editThe load_balance.type
setting can be used at the realm level to configure how Shield should interact with multiple
Active Directory servers. Shield supports both failover and load balancing modes of operation.
Table 5. 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 LDAP
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. Shield
uses the domain name to derive the LDAP URL and
|
|
no |
Specifies an LDAP URL of the form
|
|
no |
The behavior to use when there are multiple LDAP URLs defined. For supported values see LDAP load balancing and failover types. |
|
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 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 LDAP 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 Shield should follow referrals returned
by the LDAP server. Referrals are URLs returned by the
server that are to be used to continue the LDAP operation
(such as |
|
no |
Specifies whether hostname verification is performed when
connecting to an LDAP server. When |
|
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) |
Assigning Active Directory Users and Groups to Roles
editTo configure privileges for Active Directory users and groups, you assign them to roles in
the role mapping file stored on each node. You specify users and groups using their distinguished
names. For example, the following mapping configuration assigns the Active Directory admins
group both the monitoring
and user
roles, and assigns the user
role to the users
group and John Doe
.
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 a role defined in |
|
The distinguished name of the |
|
The distinguished name of the |
|
The distinguished name of the user |
For more information, see Mapping Users and Groups to Roles.
Encrypting Communications Between Shield and Active Directory with SSL/TLS
editYou should encrypt communications between Shield and Active Directory to protect the user credentials that are sent to Active Directory for authentication. Connecting via SSL/TLS ensures that the identity of the Active Directory server is authenticated before Shield transmits the user credentials, and the user names and passwords are encrypted in transit.
To encrypt communications between Shield and Active Directory:
-
Configure each node to trust certificates signed by the CA that signed your Active Directory server certificates. For example, the following command imports
cacert.pem
into node01’s keystore. (For information about using truststores, see Configuring a Separate Truststore.)cd CONFIG_DIR/shield keytool -importcert -keystore node01.jks -file cacert.pem -alias ad_ca
The CA cert must be a PEM encoded certificate.
You can also import the individual server certificates rather than the CA certificate, but this is only recommended if you have a single Active Directory server. You can fetch the Active Directory server certificate with
openssl
. For example, the following command gets the certificate forad.example.com
and stores it locally inldap.crt
.echo | openssl s_client -connect ad.example.com:636 2>/dev/null | openssl x509 > ldap.crt
If you are using an older version of openssl you might need to use use the
-host
and-port
options rather than the-connect
option. -
If you haven’t already configured the path to the node’s keystore or truststore in
elasticsearch.yml
, set theshield.ssl.keystore.path
orshield.ssl.truststore.path
attributes. For example:shield.ssl.keystore.path: /home/es/config/shield/node01.jks shield.ssl.keystore.password: myPass shield.ssl.keystore.key_password: myKeyPass
The full path to the node keystore file. This must be a location within the Elasticsearch configuration directory.
The password used to access the keystore.
The password used to access the certificate. This is only required if you specified a separate certificate password when generating the certificate.
For more information, see Enabling SSL/TLS in the Node Configuration.
-
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 to pick up the changes to
elasticsearch.yml
.
By default, when you configure Shield to connect to Active Directory using SSL/TLS,
Shield 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, Shield 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 hostname_verification
property to false
.