Secure your clusters with LDAP | Elastic Cloud Enterprise Reference [2.1]

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.

› › ›

« Verify your credentials Secure your clusters with SAML »

Secure your clusters with LDAPedit

These steps show how you can secure your 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.

Before you beginedit

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.

Configure LDAP for certificate-based authentication (version 5.0 and later)edit

For version 5.0 and later: 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 5.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": "5.5.1",
      "user_bundles": [
        {
          "name": "ldap-cert",
          "url": "https://www.myurl.com/ldapcert.zip",
          "elasticsearch_version": "5.5.1"
        },
        {
          "name": "role-mappings",
          "url": "https://www.myurl.com/role-mappings.zip",
          "elasticsearch_version": "5.5.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:
        ldap1:
          type: ldap
          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 (version 5.5 and later)edit

For version 5.5 and later: 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:
        ldap1:
          type: ldap
          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 with a role mapping file (version 2.x)edit

For version 2.x: To configure certificate-based authentication with LDAP using a role mapping file:

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

Add your user settings for LDAP, replacing myuser with your own user. The trustore section must be placed outside the realms section for these settings to work.

shield:
  ssl:
    truststore:
      path: "/app/config/trusted/trusted.ks"
      password: "PASSWORD" 
  authc:
    realms:
      ldap1:
        type: ldap
        order: 2
        url: "ldaps://SERVER_IP:636" 
        bind_dn: "uid=myuser,dc=example,dc=com"
        bind_password: PASSWORD
        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
        files:
          role_mapping: "/app/config/mappings/role_mapping.yml"
        hostname_verification: false

	The password you chose when creating the keystore.
	The IP address of the LDAP server.
	In a production environment with a trusted certificate authority, omit the `hostname_verification: false` setting. This setting skips the certificate host name check and is suitable only for testing.

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 functionality and data you expect. For example, 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 Directoryedit

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": "6.4.1",
      "user_bundles": [
        {
          "name": "ad-cert",
          "url": "https://www.myurl.com/adcert.zip",
          "elasticsearch_version": "6.4.1"
        },
        {
          "name": "role-mappings",
          "url": "https://www.myurl.com/role-mappings.zip",
          "elasticsearch_version": "6.4.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:
        type: active_directory
        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.

« Verify your credentials Secure your clusters with SAML »