Configuring Cloudera Director Server for LDAP and Active Directory

By default, the Cloudera Director server uses its own internal database to store user accounts and authorizations. You can instead configure the server to perform authentication and authorization using an external LDAP server, including Active Directory.

User and Group Model

When configured for LDAP, Cloudera Director expects that each user has an entry in an LDAP server under some base DN. When a user attempts to log in to the Cloudera Director server, the server will locate the user in LDAP and try to authenticate the user against the LDAP server using the provided password.

Cloudera Director expects that LDAP groups, collected under some base DN, are used to determine the roles that a user is authorized for. If a user is a member of a group in LDAP, then the user is granted the role that maps to that group. Multiple groups may map to the same role in Cloudera Director, and users may have multiple roles. Cloudera Director does not support the use of nested groups in LDAP to determine roles.

Basic LDAP Configuration

Determine the following pieces of information in order to configure Cloudera Director for LDAP. The same information is also needed for Active Directory.
  • The LDAP server host and port.
  • The bind DN and password that Cloudera Director should use when searching for users and groups. This account does not need administrative access to the LDAP server, but only read access for the necessary searches.
  • The base DN for user searches.
  • The filter to use for user searches or the DN pattern that all user DNs adhere to. More information on these is provided below.
  • The base DN for group searches.
  • The filter to use for group searches. More information on this is provided below.
  • The attribute of each group that forms the basis for a Cloudera Director role. More information on this is provided below.
The user search filter is employed to locate a user attempting to log in to Cloudera Director. The user's login username is substituted into the filter before it is submitted to the LDAP server. The string {0} indicates where the username is substituted.
  • To look for a username in the uid attribute of a user entry, use the filter (uid={0}).
  • To look for a username in the cn attribute of a user entry, use the filter (cn={0}).
  • For Active Directory, use the filter (sAMAccountName={0}).
Instead of specifying a user search filter, you may instead supply a user DN pattern. This avoids a search, because Cloudera Director can determine a user DN by substituting the user's login username into the pattern. The string {0} indicates where the username is substituted.
  • The user DN pattern may not be used for Active Directory. Instead, a user search filter must be supplied.
The group search is employed to locate groups that an authenticated user belongs to. The user's DN is substituted into the filter before it is submitted to the LDAP server. The string {0} indicates where the username is substituted.
  • When using the objectclass groupOfUniqueNames for user groups, use the filter (uniqueMember={0}).
  • For Active Directory, use the filter (member={0}).
The group role attribute selects which attribute of a group entry is used as the basis for determining the corresponding Cloudera Director role. Usually this is the CN of the group, but any attribute may be selected instead.
  • The group role attribute is not used for Active Directory. The group name is always used as the basis for determining a role.
The following configuration properties control basic LDAP connectivity. Additional configuration properties described in a later section are needed for Active Directory.
Configuration Property Default Meaning
lp.security.userSource internal Where to look for user data; for LDAP or Active Directory connectivity, set this to LDAP.
lp.security.ldapConfig.url N/A The LDAP URL, with host and optional port, e.g.: ldap://ldaphost:389/.
lp.security.ldapConfig.bindDn N/A The bind DN for Cloudera Director to use for searches.
lp.security.ldapConfig.bindPw N/A The bind password for Cloudera Director to use for searches.
lp.security.ldapConfig.userSearchBase N/A The base DN for user searches.
lp.security.ldapConfig.userSearchFilter N/A The user search filter, e.g., (uid={0}).
lp.security.ldapConfig.ldapDnPattern N/A The DN pattern for users.
lp.security.ldapConfig.groupSearchBase N/A The base DN for group searches.
lp.security.ldapConfig.groupSearchFilter N/A The group search filter, e.g., (uniqueMember={0}).
lp.security.ldapConfig.groupRoleAttribute N/A The group attribute to use as a basis for selecting a role, e.g., cn.

After setting or changing these configuration properties, restart the Cloudera Director server for them to take effect.

The following is an example of an LDAP configuration that points to an OpenLDAP server. Each user's uid attribute is used as their login username, and group membership is determined by the uniqueMember attribute.
lp.security.userSource: LDAP
lp.security.ldapConfig.url: ldap://openldaphost/
lp.security.ldapConfig.bindDn: cn=ldapadm,dc=domain,dc=example
lp.security.ldapConfig.bindPw: password
lp.security.ldapConfig.userSearchBase: ou=People,dc=domain,dc=example
lp.security.ldapConfig.userSearchFilter: (uid={0})
lp.security.ldapConfig.ldapDnPattern: uid={0},ou=People,dc=domain,dc=example
lp.security.ldapConfig.groupSearchBase: ou=Groups,dc=domain,dc=example
lp.security.ldapConfig.groupSearchFilter: (uniqueMember={0})
lp.security.ldapConfig.groupRoleAttribute: cn

Local User Management under LDAP

Cloudera Director does not provide user management services when configured for LDAP. To make changes to user accounts and roles, make the necessary changes in the source LDAP server. Users may need to log out of Cloudera Director and log back in for changes to take effect.

Most user API endpoints for the Cloudera Director server are disabled when the server is configured for LDAP, and will return the HTTP response code 400 (Bad Request) for any request. Also, the Cloudera Director server UI does not present user management capabilities, such as password changes, when the server is configured for LDAP.

Role Mapping

Cloudera Director maps LDAP groups to its own roles in a simple fashion.
  1. The value of the group role attribute, such as cn, is found.
  2. The value is converted to uppercase.
  3. The prefix ROLE_ is prepended.

Therefore, a group with a role attribute of admin is converted to the role ROLE_ADMIN. When using a role attribute of cn, then the DN for the group is similar to cn=admin,ou=Groups,dc=domain,dc=example.

Currently, the only roles supported by Cloudera Director are:
  • ROLE_READONLY - read-only / guest access
  • ROLE_ADMIN - full access

An administrative account should have all roles, and therefore be a member of all mapped groups.

Role mapping is more complex for Active Directory and is described below.

Active Directory Configuration

Determine the following additional pieces of information in order to configure Cloudera Director for Active Directory.
  • The domain for users and groups.
  • The desired role mapping from group names to Cloudera Director roles.
The following configuration properties control Active Directory connectivity, in addition to those for basic LDAP configuration.
Configuration Property Default Meaning
lp.security.ldapConfig.activeDirectory.domain N/A The domain.
lp.security.ldapConfig.activeDirectory.roleMapping.* N/A The role mapping (multiple properties).

After setting or changing these configuration properties, restart the Cloudera Director server for them to take effect.

The following is an example of an LDAP configuration that points to an Active Directory server. Each user's sAMAccountName attribute is used as their login username, and group membership is determined by the member attribute.
lp.security.userSource: LDAP
lp.security.ldapConfig.url: ldap://adhost/
lp.security.ldapConfig.bindDn: cn=Administrator,ou=Users,dc=domain,dc=example
lp.security.ldapConfig.bindPw: password
lp.security.ldapConfig.userSearchBase: ou=Users,dc=domain,dc=example
lp.security.ldapConfig.userSearchFilter: (sAMAccountName={0})
lp.security.ldapConfig.groupSearchBase: ou=Groups,dc=domain,dc=example
lp.security.ldapConfig.groupSearchFilter: (member={0})
lp.security.ldapConfig.activeDirectory.domain: DOMAIN.EXAMPLE
lp.security.ldapConfig.activeDirectory.roleMapping.adminGroup: admin
lp.security.ldapConfig.activeDirectory.roleMapping.readonlyGroup: readonly

Role Mapping

Cloudera Director provides flexibility in mapping the names of Active Directory groups to Cloudera Director roles. The mapping process is:
  1. The group name is searched for among the roleMapping configuration properties.
    1. If one is found, the property value is used as the base name for the role.
    2. If one is not found, the group is ignored.
  2. The base name is converted to uppercase.
  3. The prefix ROLE_ is prepended.
In the example below, two groups named group1Name and group2Name are mapped to the ROLE_READONLY Cloudera Director role, while another group3Name is mapped to the ROLE_ADMIN role.
lp.security.ldapConfig.activeDirectory.roleMapping.group1Name: readonly
lp.security.ldapConfig.activeDirectory.roleMapping.group2Name: readonly
lp.security.ldapConfig.activeDirectory.roleMapping.group3Name: admin