Secure your clusters with Active Directory
editSecure your clusters with Active Directory
editThese steps show how you can secure your Elasticsearch clusters and Kibana instances with the Lightweight Directory Access Protocol (LDAP) using an Active Directory.
Before you begin
editTo learn more about how securing Elasticsearch clusters with Active Directory works, check 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 Active Directory, you need
to configure an active_directory
realm and map Active Directory groups to user
roles in Elasticsearch.
Contrary to the ldap
realm, the active_directory
realm only supports a user
search mode, but you can choose whether to use a bind user.
Configure an Active Directory realm without a bind user
editThe Active Directory realm authenticates users using an LDAP bind request. By
default, all LDAP operations run as the authenticated user if you don’t specify
a bind_dn
. Alternatively, you can choose to
configure your realm with a bind user.
-
Add your user settings for the
active_directory
realm as follows:xpack: security: authc: realms: active_directory: my_ad: order: 2 domain_name: ad.example.com url: ldap://ad.example.com:389
The order in which the
active_directory
realm is consulted during an authentication attempt.The primary domain in Active Directory. Binding to Active Directory fails if the domain name is not mapped in DNS.
The LDAP URL pointing to the Active Directory 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, refer to using self-signed certificates.
Configure an Active Directory realm with a bind user
editYou can choose to configure an Active Directory realm using a bind user.
When you specify a bind_dn
, this specific user is used to search for the
Distinguished Name (DN
) of the authenticating user based on the provided
username and an LDAP attribute. If found, this user is authenticated by
attempting to bind to the LDAP server using the found DN
and the provided
password.
-
Add your user settings for the
active_directory
realm as follows:You must apply the user settings to each deployment template.
xpack: security: authc: realms: active_directory: my_ad: order: 2 domain_name: ad.example.com url: ldap://ad.example.com:389 bind_dn: [email protected]
The order in which the
active_directory
realm is consulted during an authentication attempt.The primary domain in Active Directory. Binding to Active Directory fails if the domain name is not mapped in DNS.
The LDAP URL pointing to the Active Directory 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, refer to using self-signed certificates.
The user to run as for all Active Directory search requests.
-
Configure the password for the
bind_dn
user 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, select Add 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 Remove by the setting name underExisting Keystores
.
-
Using self-signed certificates
editIf 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. These steps are required only if TLS is enabled and the Active Directory controller is using self-signed certificates.
You’ll prepare a custom bundle that contains your certificate
in the same way that you would on Elasticsearch Service. Custom bundles are extracted in the path
/app/config/BUNDLE_DIRECTORY_STRUCTURE
, where BUNDLE_DIRECTORY_STRUCTURE
is
the directory structure within the bundle ZIP file itself. For example:
$ tree . . └── adcert └── ca.crt
In the following example, the keystore file would be extracted to
/app/config/adcert/ca.crt
, where ca.crt
is the name of the certificate.
-
Create a ZIP file that contains your CA certificate file, such as
adcert.zip
. -
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:You must specify the
user_bundles
attribute for each deployment template. You can alter7.*
to8.*
when needed.{ "cluster_name": "REPLACE_WITH_YOUR_CLUSTER_NAME", "plan": { ... "elasticsearch": { "version": "7.*", "user_bundles": [ { "name": "adcert", "url": "https://www.myurl.com/adcert.zip", "elasticsearch_version": "7.*" } ] } }
The URL that points to the
adcert.zip
file must be accessible to the cluster. Uploaded files are stored using Amazon’s highly-available S3 service.This bundle is compatible with any Elasticsearch
7.*
version.Using a wildcard for the minor version ensures that the bundle is compatible with the specified Elasticsearch major version, and eliminates the need to upload a new bundle when upgrading to a new minor version.
-
Update your user settings for the
active_directory
realm as follows:xpack: security: authc: realms: active_directory: my_ad: order: 2 domain_name: ad.example.com url: /app/config/adcert/ca.crt bind_dn: [email protected] ssl: certificate_authorities: ["/app/config/cacerts/ca.crt"]
The
ssl.verification_mode
setting (not shown) indicates the type of verification to use when usingldaps
to protect against man-in-the-middle attacks and certificate forgery. The value for this property defaults tofull
. When you configure Elasticsearch to connect to a Domain Controller using TLS, it attempts to verify the hostname or IP address specified by theurl
attribute in the realm configuration with the Subject Alternative Names (SAN) in the certificate. If the SAN values in the certificate and realm configuration don’t match, Elasticsearch does not allow a connection to the Domain Controller. You can disable this behavior by setting thessl. verification_mode
property tocertificate
.
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 through 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 through 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 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 the custom bundle ZIP file
mappings.zip
, that contains therole-mappings.yml
file in the same way that you would on Elastic Cloud. -
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
In our example, the role mappings file is extracted to
/app/config/mappings/role-mappings.yml
-
Update your plan in the advanced configuration editor so that it uses the bundle you prepared in the previous step. Modify the
user_bundles
JSON attribute as shown in the following example:You must specify the
user_bundles
attribute for each deployment template. You can alter7.*
to8.*
when needed.{ "cluster_name": "REPLACE_WITH_YOUR_CLUSTER_NAME", "plan": { ... "elasticsearch": { "version": "7.*", "user_bundles": [ { "name": "role-mappings", "url": "https://www.myurl.com/mappings.zip", "elasticsearch_version": "7.*" } ] } }
The URL that points to
mappings.zip
must be accessible to the cluster.The bundle is compatible with any Elasticsearch
7.*
version.Using a wildcard for the minor version ensures bundles are compatible with the stated Elasticsearch major version to avoid the need to re-upload a new bundle with minor versions upgrades.
-
Update your user settings for the
ldap
realm as follows:xpack: security: authc: realms: active_directory: my_ad: order: 2 domain_name: ad.example.com url: ldaps://ad.example.com:636 bind_dn: [email protected] ssl: certificate_authorities: ["/app/config/cacerts/ca.crt"] verification_mode: certificate files: role_mapping: "/app/config/mappings/role-mappings.yml"