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 Clusters with LDAP Troubleshooting »

› › › ›

Before You Begin

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

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.

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

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 cluster, and updating your 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

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 cluster, 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.

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.

« Secure Your Clusters with LDAP Troubleshooting »