A newer version is available. For the latest information, see the current release documentation.
« Secure your 5.x and 6.x clusters with LDAP Secure your clusters with SAML »
Elastic Docs ›Elastic Cloud Enterprise Reference [3.5] ›Administering deployments ›Secure your clusters

Secure your 5.x and 6.x clusters with Active Directory

edit

Secure your 5.x and 6.x clusters with Active Directory

edit

These 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, check Secure your 7.x clusters with Active Directory.

Before you begin

edit

To 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

edit

You 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.

  1. Contrary to the ldap realm, the active_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.

  2. 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 is 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, refer to the following configuration instructions.

You must apply the user settings to each deployment template.

  1. 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: [email protected]

    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, refer to the following configuration instructions.

    This is the user that all Active Directory search requests are executed as.
  2. In versions before 6.3, you can configure a password for the bind_dn user by adding bind_password: the_password to the preceding user settings example.

  3. From version 6.3, you can configure the password for the bind_dn user by adding the appropriate secure_bind_password setting to the Elasticsearch keystore.

    1. 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.

    2. From your deployment menu, select Security.
    3. Under the Elasticsearch keystore section, select Add settings.
    4. On the Create setting window, select the secret Type to be Secret String.

    5. Set the Setting name to xpack.security.authc.realms.my_ad.secure_bind_password and add the password for the bind_dn user in the secret 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 the xpack.security.authc.realms.my_ad.secure_bind_password that was just added by using the "remove" button by the setting name under Existing Keystores.

  4. (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.

    1. Prepare the custom bundle ZIP file adcerts.zip, that contains the CA certificate file (for example ca.crt) in the same way that you would on Elastic Cloud.

    2. Custom bundles are unzipped under the path /app/config/BUNDLE_DIRECTORY_STRUCTURE, where BUNDLE_DIRECTORY_STRUCTURE is the directory structure within the bundle ZIP file itself. For example:

      $ tree .
.
└── adcerts
      └── ca.crt

      In our example, the unzipped keystore file is extracted to /app/config/adcerts/ca.crt, where ca.cert is the name of the certificate.

    3. 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.

      {
"cluster_name": "REPLACE_WITH_YOUR_CLUSTER_NAME",
"plan": {

    ...

    "elasticsearch": {
      "version": "6.*",
      "user_bundles": [
        {
          "name": "adcerts",
          "url": "https://www.myurl.com/adcerts.zip", 
          "elasticsearch_version": "6.*" 
        }
      ]
    }
  }

      The URL that points to adcerts.zip must be accessible to the cluster.

      The bundle is compatible with any Elasticsearch 6.* 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.

    4. Update 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: ldaps://ad.example.com:636 
          bind_dn: [email protected]
          ssl:
            certificate_authorities: ["/app/config/adcerts/ca.crt"]
            verification_mode: certificate

      The type of 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 to certificate.

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

edit

You 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

edit

Let’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:

  1. Create the read-only role

    POST /_xpack/security/role/read-only-my-index 
{
"indices": [
{
"names": [ "my-index" ],
"privileges": [ "read" ]
}
  ]
}

    The name of the role.

  2. Create the relevant role mapping rule for read only users

    POST /_xpack/security/role_mapping/ad-read-only 
{
"enabled": true,
"roles": [ "read-only-my-index" ], 
"rules": {
"field": { "realm.name": "my_ad" } 
},
"metadata": { "version": 1 }
}

    The name of the role mapping.

    The name of the role we created earlier.

    The name of our active directory realm.

  3. Create the relevant role mapping rule for superusers

    POST /_security/role_mapping/ldap-superuser 
{
"enabled": true,
"roles": [ "superuser" ], 
"rules": {
"all" : [
{ "field": { "realm.name": "my_ad" } },
{ "field": { "groups": "cn=administrators, dc=example, dc=com" } }
    ]
},
"metadata": { "version": 1 }
}

    The name of the role mapping.

    The name of the role we want to assign, in this case superuser.

    The name of our active_directory realm.

    The DN of the AD group whose members should get the superuser role in the deployment.

Using the Role Mapping files

edit

Let’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:

  1. 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
  2. Prepare the custom bundle ZIP file mappings.zip, that contains the role-mappings.yml file in the same way that you would on Elastic Cloud.

  3. Custom bundles get unzipped under the path /app/config/BUNDLE_DIRECTORY_STRUCTURE, where BUNDLE_DIRECTORY_STRUCTURE is the directory structure within the bundle ZIP file itself. For example:

    $ tree .
.
└── mappings
      └── role-mappings.yml

    In our example, the file is extracted to /app/config/mappings/role-mappings.yml.

  4. 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.

    {
"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 points to mappings.zip must be accessible to the cluster.

    The bundle is compatible with any Elasticsearch 6.* 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.

  5. Update your user settings for the ldap realm as follows:

    xpack:
  security:
    authc:
      realms:
        my_ad:
          type: active_directory
          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"

    The path where our role mappings file is unzipped.
« Secure your 5.x and 6.x clusters with LDAP Secure your clusters with SAML »