It is time to say goodbye: This version of Elastic Cloud Enterprise has reached end-of-life (EOL) and is no longer supported.
The documentation for this version is no longer being maintained. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Secure your 5.x and 6.x clusters with Active Directory
editSecure your 5.x and 6.x clusters with Active Directory
editThese steps show how you can secure your 5.x and 6.x Elasticsearch clusters and Kibana instances with the Lightweight Directory Access Protocol(LDAP) using an Active Directory.
For version 7.x, see Secure your 7.x clusters with Active Directory.
Before you begin
editTo learn more about how securing Elasticsearch clusters with Active Directory works, see Active Directory user authentication.
The AD credentials are valid against the deployment, not the ECE platform. You can configure role-based access control for the platform separately.
Configure authentication with Active Directory
editYou can configure the deployment to authenticate users by communicating with an Active Directory Domain Controller. To integrate with AD,
you need to configure an active_directory
realm and map AD groups to user roles in Elasticsearch.
-
Contrary to the
ldap
realm, theactive_directory
realm only supports a user search mode but you can select to use a bind user or not.The Active Directory realm authenticates users using an LDAP bind request. By default, and assuming you don’t specify a
bind_dn
, all of the LDAP operations are run by the user that is currently authenticating.When you specify a
bind_dn
, this specific user is used to search for the DN of the authenticating user based on the provided username and an LDAP attribute. Once found, the user is authenticated by attempting to bind to the LDAP server using the found DN and the provided password. -
To configure an active directory realm, add your user settings for the
active_directory
realm as follows:xpack: security: authc: realms: my_ad: type: active_directory order: 2 domain_name: ad.example.com url: ldap://ad.example.com:389
The type of the realm, should be
active_directory
.The order in which the active_directory realm will be consulted during an authentication attempt.
The primary domain in AD. Note that binding to Active Directory fails if the domain name is not mapped in DNS.
The LDAP URL pointing to the AD Domain Controller that should handle authentication. 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, see below for configuration instructions
-
Alternatively, to configure an active directory realm using a bind user , add your user settings for the
active_directory
realm as follows:xpack: security: authc: realms: my_ad: type: active_directory order: 2 domain_name: ad.example.com url: ldap://ad.example.com:389 bind_dn: es_svc_user@ad.example.com
The type of the realm, should be
active_directory
.The order in which the active_directory realm will be consulted during an authentication attempt.
The primary domain in AD. Note that binding to Active Directory fails if the domain name is not mapped in DNS.
The LDAP URL pointing to the AD Domain Controller that should handle authentication. 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, see below for configuration instructions.
This is the user that all Active Directory search requests are executed as.
-
In versions before 6.3, the password for the
bind_dn
user can be configured by addingbind_password: the_password
in the user settings above -
In versions after 6.3, the password for the
bind_dn
user should be configured by adding the appropriatesecure_bind_password
setting to the Elasticsearch keystore.-
From the Deployments page, select your deployment.
Narrow the list by name, ID, or choose from several other filters. To further define the list, use a combination of filters.
- From your deployment menu, select Security.
- Under the Elasticsearch Keystore section, click Create settings.
-
On the Create setting window, select the secret Type to be
Secret String
. -
Set the Setting name` to
xpack.security.authc.realms.active_directory.my_ad.secure_bind_password
and add the password for thebind_dn
user in thesecret
field.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 wish to rollback the Active Directory realm related configuration effort, you need to remove thexpack.security.authc.realms.active_directory.my_ad.secure_bind_password
that was just added by clicking on the "remove" button by the setting name underExisting Keystores
.
-
-
(Optional) Encrypt communications between the deployment and the Domain Controller. If your LDAP server 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.
-
Prepare a custom bundle as a ZIP file that contains the CA certificate file (for example
ca.crt
) inside of acacerts
folder` in the same way that you would on Elastic Cloud. -
Update your plan in the advanced configuration editor so that it uses the bundle you prepared in the previous step. You need to modify the
user_bundles
JSON attribute similar to the following example:{ "cluster_name": "REPLACE_WITH_YOUR_CLUSTER_NAME", "plan": { ... "elasticsearch": { "version": "6.*", "user_bundles": [ { "name": "ldap-cert", "url": "https://www.myurl.com/adcert.zip", "elasticsearch_version": "6.*" } ] } }
The URL that point to
adcert.zip
must be accessible to the cluster. Also, when you*
a minor versions bundles are compatible with any Elasticsearch major version to avoid a need to re-upload a new bundle with minor versions upgrade. In this example the bundle is compatible with any Elasticsearch 6.* version. -
Custom bundles get unzipped under the path
/app/config/BUNDLE_DIRECTORY_STRUCTURE
, whereBUNDLE_DIRECTORY_STRUCTURE
is the directory structure within the bundle ZIP file itself. For example:$ tree . . └── cacerts └── ca.crt
So in our example, the unzipped keystore file gets placed under
/app/config/cacerts/ca.crt
-
Update your user settings for the
active_directory
realm as followsxpack: security: authc: realms: my_ad: type: active_directory 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
The type of the realm, should be
active_directory
.The
ldaps
URL pointing to the AD Domain Controller.(Optional) By default, when you configure Elasticsearch to connect to an Domain Controller using SSL/TLS, it 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, Elasticsearch does not allow a connection to the Domain Controller. 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 tocertificate
.
-
Prepare a custom bundle as a ZIP file that contains the CA certificate file (for example
If your CA certificate is available as a JKS
or PKCS#12
keystore, you can upload that file in the ZIP bundle ( for example
create a ZIP archive from a truststore
folder that contains a file named ca.p12
) and then reference it in the user settings with
xpack.security.authc.realms.my_ad.ssl.truststore.path: "/app/config/truststore/ca.p12"
. If the keystore is also password protected (
which is unusual for keystores that contain only CA certificates ), you can also provide the password for the keystore by adding
xpack.security.authc.realms.my_ad.ssl.truststore.password: password
in the user settings.
Mapping Active Directory groups to roles
editYou have two ways of mapping Active Directory groups to roles for your users. The preferred one is to use the Role Mapping API. If for some reason this is not possible, you can use a role mapping file to specify the mappings instead.
Only Active Directory security groups are supported. You cannot map distribution groups to roles.
Using the Role Mapping API
editLet’s assume that you want all your users that authenticate via AD to have read only access to a certain index my-index
and the AD
users that are members of the `cn=administrators, dc=example, dc=com" group in LDAP, to become superusers in your
deployment:
-
Create the read-only role
-
Create the relevant role mapping rule for read only users
-
Create the relevant role mapping rule for superusers
Using the Role Mapping files
editLet’s assume that you want all your users that authenticate via AD and are members of the cn=my-users,dc=example, dc=com
group in
AD to have read only access to a certain index my-index
and only the users
`cn=Senior Manager, cn=management, dc=example, dc=com" and
`cn=Senior Admin, cn=management, dc=example, dc=com" to become superusers in your deployment:
-
Create a file name named role-mappings.yml with the following contents
superuser: - cn=Senior Manager, cn=management, dc=example, dc=com - cn=Senior Admin, cn=management, dc=example, dc=com read-only-user: - cn=my-users, dc=example, dc=com
-
Prepare a custom bundle as a ZIP file that contains the role-mappings.yml file inside of a
mappings
folder` in the same way that you would on Elastic Cloud. -
Update your plan in the advanced configuration editor so that it uses the bundle you prepared in the previous step. You need to modify the
user_bundles
JSON attribute similar to the following example:{ "cluster_name": "REPLACE_WITH_YOUR_CLUSTER_NAME", "plan": { ... "elasticsearch": { "version": "6.*", "user_bundles": [ { "name": "role-mappings", "url": "https://www.myurl.com/mappings.zip", "elasticsearch_version": "6.*" } ] } }
The URL that point to
mappings.zip
must be accessible to the cluster. Also, when you*
a minor versions bundles are compatible with any Elasticsearch major version to avoid a need to re-upload a new bundle with minor versions upgrade. In this example the bundle is compatible with any Elasticsearch 6.* version.-
Custom bundles get unzipped under the path
/app/config/BUNDLE_DIRECTORY_STRUCTURE
, whereBUNDLE_DIRECTORY_STRUCTURE
is the directory structure within the bundle ZIP file itself. For example:$ tree . . └── mappings └── role-mappings.yml
So in our example, the unzipped role mappings file gets placed under
/app/config/mappings/role-mappings.yml
-
Update your user settings for the
ldap
realm as follows (building from previous examples)xpack: security: authc: realms: my_ad: type: active_directory 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"
-