417 lines
25 KiB
Plaintext
417 lines
25 KiB
Plaintext
[[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`.
|