druid/docs/operations/auth-ldap.md

id	title
auth-ldap	LDAP auth

This page describes how to set up Druid user authentication and authorization through LDAP. The first step is to enable LDAP authentication and authorization for Druid. You then map an LDAP group to roles and assign permissions to roles.

Enable LDAP in Druid

Before starting, verify that the active directory is reachable from the Druid Master servers. Command line tools such as ldapsearch and ldapwhoami, which are included with OpenLDAP, are useful for this testing. 

Check the connection

First test that the basic connection and user credential works. For example, given a user uuser1@example.com, try:

ldapwhoami -vv -H ldap://<ip_address>:389  -D"uuser1@example.com" -W

Enter the password associated with the user when prompted and verify that the command succeeded. If it didn't, try the following troubleshooting steps:

• Verify that you've used the correct port for your LDAP instance. By default, the LDAP port is 389, but double-check with your LDAP admin if unable to connect.
• Check whether a network firewall is not preventing connections to the LDAP port.
• Check whether LDAP clients need to be specifically whitelisted at the LDAP server to be able to reach it. If so, add the Druid Coordinator server to the AD whitelist.

Check the search criteria

After verifying basic connectivity, check your search criteria. For example, the command for searching for user uuser1@example.com  is as follows:

ldapsearch -x -W -H ldap://<ldap_server>  -D"uuser1@example.com" -b "dc=example,dc=com" "(sAMAccountName=uuser1)"

Note the memberOf attribute in the results; it shows the groups that the user belongs to. You will use this value to map the LDAP group to the Druid roles later. This attribute may be implemented differently on different types of LDAP servers. For instance, some LDAP servers may support recursive groupings, and some may not. Some LDAP server implementations may not have any object classes that contain this attribute altogether. If your LDAP server does not use the memberOf attribute, then Druid will not be able to determine a user's group membership using LDAP. The sAMAccountName attribute used in this example contains the authenticated user identity. This is an attribute of an object class specific to Microsoft Active Directory. The object classes and attribute used in your LDAP server may be different.

Configure Druid user authentication with LDAP/Active Directory 

1. Enable the druid-basic-security extension in the common.runtime.properties file. See Security Overview for details.

2. As a best practice, create a user in LDAP to be used for internal communication with Druid.

3. In common.runtime.properties, update LDAP-related properties, as shown in the following listing: 

   druid.auth.authenticatorChain=["ldap"]
   druid.auth.authenticator.ldap.type=basic
   druid.auth.authenticator.ldap.enableCacheNotifications=true
   druid.auth.authenticator.ldap.credentialsValidator.type=ldap
   druid.auth.authenticator.ldap.credentialsValidator.url=ldap://<AD host>:<AD port>
   druid.auth.authenticator.ldap.credentialsValidator.bindUser=<AD admin user, e.g.: Administrator@example.com>
   druid.auth.authenticator.ldap.credentialsValidator.bindPassword=<AD admin password>
   druid.auth.authenticator.ldap.credentialsValidator.baseDn=<base dn, e.g.: dc=example,dc=com>
   druid.auth.authenticator.ldap.credentialsValidator.userSearch=<The LDAP search, e.g.: (&(sAMAccountName=%s)(objectClass=user))>
   druid.auth.authenticator.ldap.credentialsValidator.userAttribute=sAMAccountName
   druid.auth.authenticator.ldap.authorizerName=ldapauth
   druid.escalator.type=basic
   druid.escalator.internalClientUsername=<AD internal user, e.g.: internal@example.com>
   druid.escalator.internalClientPassword=Welcome123
   druid.escalator.authorizerName=ldapauth
   druid.auth.authorizers=["ldapauth"]
   druid.auth.authorizer.ldapauth.type=basic
   druid.auth.authorizer.ldapauth.initialAdminUser=AD user who acts as the initial admin user, e.g.: internal@example.com>
   druid.auth.authorizer.ldapauth.initialAdminRole=admin
   druid.auth.authorizer.ldapauth.roleProvider.type=ldap
   

   Notice that the LDAP user created in the previous step, internal@example.com, serves as the internal client user and the initial admin user.

Use LDAP groups to assign roles

You can map LDAP groups to a role in Druid. Members in the group get access to the permissions of the corresponding role. 

Step 1: Create a role

First create the role in Druid using the Druid REST API.

Creating a role involves submitting a POST request to the Coordinator process. 

The following REST APIs to create the role to read access for datasource, config, state.

As mentioned, the REST API calls need to address the Coordinator node. The examples used below use localhost as the Coordinator host and 8081 as the port. Adjust these settings according to your deployment.

Call the following API to create role readRole . 

curl -i -v  -H "Content-Type: application/json" -u internal -X POST  http://localhost:8081/druid-ext/basic-security/authorization/db/ldapauth/roles/readRole 

Check that the role has been created successfully by entering the following:

curl -i -v  -H "Content-Type: application/json" -u internal -X GET  http://localhost:8081/druid-ext/basic-security/authorization/db/ldapauth/roles

Step 2: Add permissions to a role 

You can now add one or more permission to the role. The following example adds read-only access to a wikipedia data source.  

Given the following JSON in a file named perm.json:

[{ "resource": { "name": "wikipedia", "type": "DATASOURCE" }, "action": "READ" }
,{ "resource": { "name": ".*", "type": "STATE" }, "action": "READ" },
{ "resource": {"name": ".*", "type": "CONFIG"}, "action": "READ"}]

The following command associates the permissions in the JSON file with the role

curl -i -v  -H "Content-Type: application/json" -u internal -X POST -d@perm.json  http://localhost:8081/druid-ext/basic-security/authorization/db/ldapauth/roles/readRole/permissions

Note that the STATE and CONFIG permissions in perm.json are needed to see the data source in the web console. If only querying permissions are needed, the READ action is sufficient:

[{ "resource": { "name": "wikipedia", "type": "DATASOURCE" }, "action": "READ" }]

You can also provide the name in the form of regular expression. For example, to give access to all data sources starting with wiki, specify the name as  { "name": "wiki.*", ......

Step 3: Create group Mapping 

The following shows an example of a group to role mapping. It assumes that a group named group1 exists in the directory. Also assuming the following role mapping in a file named groupmap.json:

{
    "name": "group1map",
    "groupPattern": "CN=group1,CN=Users,DC=example,DC=com",
    "roles": [
        "readRole"
    ]
}

You can configure the mapping as follows:

curl -i -v  -H "Content-Type: application/json" -u internal -X POST -d @groupmap.json http://localhost:8081/druid-ext/basic-security/authorization/db/ldapauth/groupMappings/group1map

To check whether the group mapping was created successfully, run the following command:

curl -i -v  -H "Content-Type: application/json" -u internal -X GET http://localhost:8081/druid-ext/basic-security/authorization/db/ldapauth/groupMappings

To check the details of a specific group mapping, use the following:

curl -i -v  -H "Content-Type: application/json" -u internal -X GET http://localhost:8081/druid-ext/basic-security/authorization/db/ldapauth/groupMappings/group1map

To add additional roles to the group mapping, use the following API:

curl -i -v  -H "Content-Type: application/json" -u internal -X POST http://localhost:8081/druid-ext/basic-security/authorization/db/ldapauth/groupMappings/group1/roles/<newrole> 

In the next two steps you will be creating a user, and assigning previously created roles to it. These steps are only needed in the following cases:

• Your LDAP server does not support the memberOf attribute, or
• You want to configure a user with additional roles that are not mapped to the group(s) that the user is a member of

If this is not the case for your scenario, you can skip these steps.

Step 4. Create a user

Once LDAP is enabled, only user passwords are verified with LDAP. You add the LDAP user to Druid as follows: 

curl -i -v  -H "Content-Type: application/json" -u internal -X POST http://localhost:8081/druid-ext/basic-security/authentication/db/ldap/users/<AD user> 

Step 5. Assign the role to the user

The following command shows how to assign a role to a user:

curl -i -v  -H "Content-Type: application/json" -u internal -X POST http://localhost:8081/druid-ext/basic-security/authorization/db/ldapauth/users/<AD user>/roles/<rolename> 

For more information about security and the basic security extension, see Security Overview.