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 settings Secure your 5.x and 6.x clusters with LDAP or Active Directory »

› › ›

Secure your 7.x clusters with LDAP or Active Directory

edit

Secure your 7.x clusters with LDAP or Active Directory

edit

These steps show how you can secure your 7.x Elasticsearch clusters and Kibana instances with the Lightweight Directory Access Protocol (LDAP). To authenticate users through LDAP, you must first configure an ldap realm and map LDAP groups to user roles using the X-Pack security features.

For version 5.x and 6.x, see Secure your 5.x and 6.x clusters with LDAP or Active Directory.

Before you begin

edit

The steps in this section require an understanding of LDAP. To learn more about how securing Elasticsearch clusters with LDAP works, see LDAP user authentication.

The LDAP credentials are valid against the deployment, not the ECE platform. You can try out our beta release of role-based access control for the platform.

Configure LDAP for certificate-based authentication

edit

To configure certificate-based authentication that uses LDAP over SSL:

Create an LDAP realm.
1. Decide which type of verification to perform when connecting to a LDAP server:
  - For self-signed certificates: Use ssl.verification_mode: certificate together with the ssl.truststore.path and ssl.truststore.password settings.
  - For certificates issued by a trusted source: Use ssl.verification_mode: full together with the ssl.truststore.path and ssl.truststore.password settings.
2. Create some LDAP entries. In this example, there is one organizational unit groups with the administrators and readonly groups under it. All of the entries are part of the domain LDAP object dc=example,dc=com.
```
admin:
  - "cn=administrators,ou=groups,dc=example,dc=com"
readonly:
  - "cn=users,ou=groups,dc=example,dc=com"
```
Prepare a custom bundle as a ZIP file that contains your keystore file with the private key and certificate inside of a truststore folder` in the same way that you would on Elastic Cloud. This bundle allows all Elasticsearch containers to access the same keystore file through your ssl.truststore settings.
Prepare a custom bundle ZIP file with a role mapping file contained inside a mappings folder. The contents of the role mapping file in our example are:
```
admin:
  - "cn=administrators,ou=groups,dc=example,dc=com"
readonly:
  - "cn=users,ou=groups,dc=example,dc=com"
```
Create a deployment in the Cloud UI that you will update for use with LDAP later on. Use Elasticsearch version 7.x or later.

Update your new Elasticsearch cluster in the advanced configuration editor so that it uses the bundles you prepared in a previous step. You need to modify the user_bundles JSON attribute similar to the following example:

{
  "cluster_name": "xxxxxxx",
  "plan": {

    ...

    "elasticsearch": {
      "version": "7.1.1",
      "user_bundles": [
        {
          "name": "ldap-cert",
          "url": "https://www.myurl.com/ldapcert.zip",
          "elasticsearch_version": "7.1.1"
        },
        {
          "name": "role-mappings",
          "url": "https://www.myurl.com/role-mappings.zip",
          "elasticsearch_version": "7.1.1"
        }
      ]
    }
  }

The URLs that point to the bundle ZIP files (here ldapcert.zip and role-mappings.zip) must be accessible to the cluster.

Note the file locations where custom bundles get unzipped, you will need them in the next step. 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 .
.
└── truststore
      └── keystore.ks
```
In our example, the unzipped keystore file gets placed under /app/config/truststore/keystore.ks and the unzipped role mappings file under /app/config/mappings/role-mappings.yml.

Add your user settings for the ldap realm for your users and groups, and specify your keystore and role mapping files from the previous step. For example:

xpack:
  security:
    authc:
      realms:
        ldap.ldap1:
          order: 2
          url: "ldaps://SERVER_IP:636" 
          user_search:
            base_dn: "dc=example,dc=com"
            attribute: cn
          group_search:
            base_dn: "ou=groups,dc=example,dc=com"
          ssl:
            verification_mode: certificate
            truststore:
              path: "/app/config/truststore/keystore.ks"
              password: "PASSWORD" 
          files:
            role_mapping: "/app/config/mappings/role-mappings.yml"
          unmapped_groups_as_roles: false

	The IP address of the LDAP server.
	The password you chose when creating the keystore.

If you set the realm type to native, the cluster fails to start. Do not combine the native realm with other authentication methods.

After the cluster configuration is updated, log into Kibana with the different users in your LDAP realm and verify that they can access the product features and data you expect. For example, in this case the readonly user should be able to read indices based on the roles you granted, but it should not be able to write to indices or manage security features.

Configure LDAP with the role mapping API

edit

To configure certificate-based authentication with LDAP using the Role Mapping API:

Follow steps 1 through 5 in the previous section, excluding step 3. These steps walk you through configuring an LDAP realm, creating a custom bundle with your keystore file, creating a deployment, and updating your Elasticsearch cluster configuration to use the bundle.

Edit the user settings for your cluster to add minimal LDAP settings, replacing SERVER_IP with your own information:

xpack:
  security:
    authc:
      realms:
        ldap.ldap1:
          order: 2
          url: "ldap://SERVER_IP:389"
          user_search:
            base_dn: "dc=example,dc=com"
            attribute: cn
          group_search:
            base_dn: "ou=groups,dc=example,dc=com"
          unmapped_groups_as_roles: false

If you set the realm type to native, the cluster fails to start. Do not combine the native realm with other authentication methods.

Map roles to your users with the Role Mapping API. For example, you can create an admin user with roles that map to the elastic superuser role and a readonly user that maps to some read-only roles.
After the cluster configuration is updated, log into Kibana with the different users in your LDAP realm and verify that they can access the functionality and data you expect. For example, in this case, the readonly user should be able to read indices based on the roles you granted, but it should not be able to write to indices or manage security features.

Configure LDAP and Active Directory

edit

The steps in this section require an understanding of Active Directory. To learn more about how securing Elasticsearch clusters with Active Directory works, see AD user authentication.

To configure LDAP with Active Directory:

Create or use an existing deployment.
If you are planning to encrypt the communication between ECE and the Active directory, upload a custom bundle as a ZIP file to your Elasticsearch cluster in the advanced configuration editor.

The bundle should contain your keystore file with the private key and certificate inside of a truststore folder allowing all Elasticsearch containers to access the same keystore file through your ssl.truststore settings.

You need to modify the user_bundles JSON attribute similar to the following example:
```
{
  "cluster_name": "xxxxxxx",
  "plan": {

    ...

    "elasticsearch": {
      "version": "7.1.1",
      "user_bundles": [
        {
          "name": "ad-cert",
          "url": "https://www.myurl.com/adcert.zip",
          "elasticsearch_version": "7.1.1"
        },
        {
          "name": "role-mappings",
          "url": "https://www.myurl.com/role-mappings.zip",
          "elasticsearch_version": "7.1.1"
        }
      ]
    }
  }
```
The URLs that point to the bundle ZIP files (here ldapcert.zip and role-mappings.zip) must be accessible to the cluster.
Restart the Elasticsearch cluster.

Configure the user settings for your Elasticsearch cluster to use Active Directory:

xpack:
  security:
    authc:
      realms:
        active_directory:
          my_ad:
            order: 2
            domain_name: AD_DOMAIN_NAME.com
            url: ldaps://SERVER_IP:636
            user_search:
              base_dn: "dc=example,dc=com"
              attribute: cn
            group_search:
              base_dn: "ou=groups,dc=example,dc=com"
              unmapped_groups_as_roles: false
            ssl:
              verification_mode: certificate
              truststore:
                path: "/app/config/pem/keystore.ks"
                password: "secret"

There are three SSL verification mode options:

certificate for self-signed certificates. Must include the path and password.
full for certificates issued by a trusted source. Must include the path and password.
none where all certificates are trusted, regardless of issuer.

Alternatively, you can remove these lines entirely to avoid using SSL.

After the cluster configuration is updated, log into Kibana with the different users in your Active Directory realm and verify that they can access the product features and data you expect. For example, in this case the readonly user should be able to read indices based on the roles you granted, but they should not be able to write to indices or manage security features.

If you set the realm type to native, the cluster fails to start. Do not combine the native realm with other authentication methods.

« Secure your settings Secure your 5.x and 6.x clusters with LDAP or Active Directory »