diff --git a/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc b/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc index 143156ca636a6..d76f6978688b0 100644 --- a/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc +++ b/x-pack/docs/en/security/authentication/active-directory-realm.asciidoc @@ -6,14 +6,7 @@ users. To integrate with Active Directory, you configure an `active_directory` realm and map Active Directory users and groups to {security} roles in the <>. -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 -<>. - -==== Configuring an Active Directory Realm +See {ref}/configuring-ad-realm.html[Configuring an Active Directory Realm]. {security} uses LDAP to communicate with Active Directory, so `active_directory` realms are similar to <>. Like LDAP directories, @@ -39,132 +32,6 @@ Active Directory. Once 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 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 <> -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> ------------------------------------------------------------- -<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::389`. -+ -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. - -===== Configuring a Bind User -By default, all of the LDAP operations are run by the user that {security} 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 will be used to perform all operations other than the LDAP -bind request, which is required to authenticate the credentials provided by the user. - -The use of a bind user enables the <> to be -used with the Active Directory realm and the ability to maintain a set of pooled -connections to Active Directory. These pooled connection reduce the number of -resources that must be created and destroyed with every user authentication. - -The following example shows the configuration of a bind user through the user of the -`bind_dn` and `secure_bind_password` settings. - -[source, yaml] ------------------------------------------------------------- -xpack: - security: - authc: - realms: - active_directory: - type: active_directory - order: 0 - domain_name: ad.example.com - url: ldaps://ad.example.com:636 - bind_dn: es_svc_user@ad.example.com <1> ------------------------------------------------------------- -<1> This is the user that all Active Directory search requests are executed as. - Without a bind user configured, all requests run as the user that is authenticating - with Elasticsearch. - -The password for the `bind_dn` user should be configured by adding the appropriate -`secure_bind_password` setting to the {es} keystore. -For example, the following command adds the password for the example realm above: - -[source, shell] ------------------------------------------------------------- -bin/elasticsearch-keystore add xpack.security.authc.realms.active_directory.secure_bind_password ------------------------------------------------------------- - -When a bind user is configured, connection pooling is enabled by default. -Connection pooling can be disabled using the `user_search.pool.enabled` setting. - -===== 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 `@ - } }, - "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 <>. +See {ref}/configuring-ad-realm.html[Configuring an Active Directory realm]. [[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 -<> in roles. +properties are populated in the user's _metadata_: |======================= | Field | Description @@ -270,51 +64,15 @@ properties are populated in the user's _metadata_. This metadata is returned in groups were mapped to a role). |======================= +This metadata is returned in the +{ref}/security-api-authenticate.html[authenticate API] and can be used with +<> in roles. + 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 `certificate`. +See +{ref}/configuring-tls.html#tls-active-directory[Encrypting communications between {es} and Active Directory]. \ No newline at end of file diff --git a/x-pack/docs/en/security/authentication/configuring-active-directory-realm.asciidoc b/x-pack/docs/en/security/authentication/configuring-active-directory-realm.asciidoc new file mode 100644 index 0000000000000..6298bb8ef9f54 --- /dev/null +++ b/x-pack/docs/en/security/authentication/configuring-active-directory-realm.asciidoc @@ -0,0 +1,248 @@ +[role="xpack"] +[[configuring-ad-realm]] +=== Configuring an Active Directory realm + +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 role +mapping file. + +For more information about Active Directory realms, see +{xpack-ref}/active-directory-realm.html[Active Directory User Authentication]. + +. 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`. 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 <> 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> +------------------------------------------------------------ +<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::389`. + +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. +-- + +. If you are authenticating users across multiple domains in a forest, extra +steps are required. There are a few minor differences in the configuration and +the way that users authenticate. ++ +-- +Set the `domain_name` setting to the forest root domain name. + +You must also set the `url` setting, since you must authenticate against the +Global Catalog, which uses a different port and might 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 `@>. +-- + +. (Optional) To protect passwords, +<>. + +. Restart {es}. + +. Configure 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 {security} 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. + +The use of a bind user enables the +{xpack-ref}/run-as-privilege.html[run as feature] to be used with the Active +Directory realm and the ability to maintain a set of pooled connections to +Active Directory. These pooled connection reduce the number of resources that +must be created and destroyed with every user authentication. + +The following example shows the configuration of a bind user through the user of +the `bind_dn` and `secure_bind_password` settings: + +[source, yaml] +------------------------------------------------------------ +xpack: + security: + authc: + realms: + active_directory: + type: active_directory + order: 0 + domain_name: ad.example.com + url: ldaps://ad.example.com:636 + bind_dn: es_svc_user@ad.example.com <1> +------------------------------------------------------------ +<1> This is the user that all Active Directory search requests are executed as. + Without a bind user configured, all requests run as the user that is authenticating + with {es}. + +The password for the `bind_dn` user should be configured by adding the +appropriate `secure_bind_password` setting to the {es} keystore. For example, +the following command adds the password for the example realm above: + +[source, shell] +------------------------------------------------------------ +bin/elasticsearch-keystore add \ +xpack.security.authc.realms.active_directory.secure_bind_password +------------------------------------------------------------ + +When a bind user is configured, connection pooling is enabled by default. +Connection pooling can be disabled using the `user_search.pool.enabled` setting. +-- + +. Map 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 <> 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 +{xpack-ref}/mapping-roles.html[Mapping users and groups to roles]. +-- + +. (Optional) Configure the `metadata` setting in the Active Directory realm to +include extra properties in the user's metadata. ++ +-- +By default, `ldap_dn` and `ldap_groups` are populated in the user's metadata. +For more information, see +{xpack-ref}/active-directory-realm.html#ad-user-metadata[User Metadata in Active Directory Realms]. +-- diff --git a/x-pack/docs/en/security/configuring-es.asciidoc b/x-pack/docs/en/security/configuring-es.asciidoc index aab00fb225fd6..3efc682216faf 100644 --- a/x-pack/docs/en/security/configuring-es.asciidoc +++ b/x-pack/docs/en/security/configuring-es.asciidoc @@ -70,6 +70,9 @@ user API. -- +. Choose which types of realms you want to use to authenticate users. +** <>. + . Set up roles and users to control access to {es}. For example, to grant _John Doe_ full access to all indices that match the pattern `events*` and enable him to create visualizations and dashboards @@ -128,5 +131,6 @@ include::securing-communications/securing-elasticsearch.asciidoc[] include::securing-communications/configuring-tls-docker.asciidoc[] include::securing-communications/enabling-cipher-suites.asciidoc[] include::securing-communications/separating-node-client-traffic.asciidoc[] +include::authentication/configuring-active-directory-realm.asciidoc[] include::{xes-repo-dir}/settings/security-settings.asciidoc[] include::{xes-repo-dir}/settings/audit-settings.asciidoc[] diff --git a/x-pack/docs/en/security/securing-communications/securing-elasticsearch.asciidoc b/x-pack/docs/en/security/securing-communications/securing-elasticsearch.asciidoc index b100567edf8b9..e5c1187264f7c 100644 --- a/x-pack/docs/en/security/securing-communications/securing-elasticsearch.asciidoc +++ b/x-pack/docs/en/security/securing-communications/securing-elasticsearch.asciidoc @@ -20,9 +20,13 @@ information, see <>. .. Required: <>. .. Recommended: <>. +. If you are using Active Directory user authentication, +<>. + For more information about encrypting communications across the Elastic Stack, see {xpack-ref}/encrypting-communications.html[Encrypting Communications]. include::node-certificates.asciidoc[] include::tls-transport.asciidoc[] include::tls-http.asciidoc[] +include::tls-ad.asciidoc[] diff --git a/x-pack/docs/en/security/securing-communications/tls-ad.asciidoc b/x-pack/docs/en/security/securing-communications/tls-ad.asciidoc new file mode 100644 index 0000000000000..d189501f1e2a5 --- /dev/null +++ b/x-pack/docs/en/security/securing-communications/tls-ad.asciidoc @@ -0,0 +1,57 @@ +[role="xpack"] +[[tls-active-directory]] +==== Encrypting communications between {es} and Active Directory + +To protect the user credentials that are sent for authentication, it's highly +recommended to encrypt communications between {es} 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. + +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. + +. Create the realm configuration for the `xpack.security.authc.realms` namespace +in the `elasticsearch.yml` file. See <>. + +. 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`. + +. Configure each node to trust certificates signed by the certificate authority +(CA) that signed your Active Directory server certificates. ++ +-- +The following example demonstrates how to trust a CA certificate (`cacert.pem`), +which is located within the 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/cacert.pem" ] +-------------------------------------------------- + +The CA cert must be a PEM encoded certificate. + +For more information about these settings, see <>. +-- + +. Restart {es}. + +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 + `ssl.verification_mode` property to `certificate`.