Integrating Hue with LDAP

This topic explains how to configure Hue so that it authenticates against an LDAP directory server. When Hue is integrated with LDAP, users can authenticate with their existing credentials and transparently inherit existing groups.

When authenticating with LDAP, Hue validates login credentials against an LDAP directory service if configured with the LDAP authentication backend:

The LDAP authentication backend automatically creates users in Hue that do not exist. Hue imports these users (but never passwords) to properly authenticate.

To limit users to a predefined list, disable automatic user import by setting create_users_on_login=false under [desktop] > [[ldap]] in hue.ini.

There are two ways to authenticate with a directory service through Hue:

  • Search Bind: Hue searches for credentials to bind to the LDAP server
  • Direct Bind: Hue directly binds to the LDAP server with given credentials
Specify the authentication mechanism with search_bind_authentication under [desktop] > [[ldap]] in hue.ini.
search_bind_authentication Uses search bind authentication by default. Set this property to false to use direct bind authentication.

Default: true

Search Bind

Search bind authentication performs an ldapsearch against the directory service and binds with the found distinguished name (DN) and password. This is the default method used by Hue with LDAP.

You can define how Hue uses search to bind to the LDAP server with the following properties under [desktop] > [[ldap]] > [[[users]]] in hue.ini.

user_filter General LDAP filter to restrict search.

Default: "objectclass=*"

user_name_attr The username to be searched against. Typical attributes to search for include: uid, sAMAccountName.

Default: sAMAccountName

With the above configuration, the LDAP search filter takes on the form:
(&(objectClass=*)(sAMAccountName=<user entered username>))

Direct Bind

Direct bind authentication binds to the LDAP server with the username and password provided at login.

You can define how Hue directly binds to the LDAP server with the following properties under [desktop] > [[ldap]] in hue.ini.
nt_domain The NT domain to connect to (only for use with Active Directory). Typically maps to the user email address or ID in conjunction with the domain. This AD-specific property allows Hue to authenticate without having to follow LDAP references to other partitions.

If provided, Hue binds with User Principal Names (UPNs).


ldap_username_pattern Provides a template for the DN that is sent to the directory service when authenticating. The <username> parameter is replaced with the username provided at login.

Default: "uid=<username>,ou=People,dc=mycompany,dc=com"

Importing LDAP Users and Groups

If an LDAP user needs to be part of a certain group and be given a particular set of permissions, you can import this user with the User Admin interface in Hue.

Groups can also be imported using the User Admin interface, and users can be added to this group. As in the image below, not only can groups be discovered using DN and rDN search, but users that are members of the group or members of its subordinate groups can be imported as well.

You have the following options available when importing a user/group:

  • Distinguished name: If checked, the username provided must be a full distinguished name (for example, uid=hue,ou=People,dc=gethue,dc=com). Otherwise, the Username provided should be a fragment of a Relative Distinguished Name (rDN) (for example, the username hue maps to the rDN uid=hue). Hue performs an LDAP search using the same methods and configurations as described above. That is, Hue takes the provided username and creates a search filter using the user_filter and user_name_attr configurations.
  • Create home directory: If checked, when the user is imported, their home directory in HDFS is automatically be created if it doesn’t already exist.

Synchronizing LDAP Users and Groups

Users and groups can be synchronized with the directory service using the User Admin interface or using a command line utility. The image from the Importing LDAP Users and Groups section uses the words Add/Sync to indicate that when a user or group that already exists in Hue is being added, it is, in fact, synchronized instead. In the case of importing users for a particular group, new users are imported and existing users are synchronized.

Attributes Synchronized

Currently, only the first name, last name, and email address are synchronized. Hue looks for the LDAP attributes givenName, sn, and mail when synchronizing. The user_name_attr configuration property is used to appropriately choose the username in Hue. For instance, if user_name_attr’ is set to uid”, then the "uid" returned by the directory service is used as the username of the user in Hue.

User Admin interface

The Sync LDAP users/groups button in the User Admin interface will automatically synchronize all users and groups.

Synchronize Using a Command-Line Interface

For example, to synchronize users and groups using a command-line interface:

<hue root>/build/env/bin/hue sync_ldap_users_and_groups

Configuring Hue for Authentication against Multiple LDAP/Active Directory Servers

Hue also supports the ability to authenticate against multiple LDAP servers. Before attempting LDAP authentication against multiple servers, ensure you have configured LDAP synchronization for each server, as described in the previous section. As long as users and groups are synced across LDAP and Hue, authentication should work.

To configure multiple servers, determine the correct parameters for each server as described in the Integrating Hue with LDAP section above. In the hue.ini file, create a configuration section for each LDAP server under [[[ldap_servers]]] named for the respective LDAP server, with the format [[[[<ldap_server>]]]].

If you are using Cloudera Manager, you can add the configuration section using an Advanced Configuration Snippet:

  1. Go to the Hue Service.
  2. Click Configuration.
  3. Select Category > Advanced.
  4. Locate the Hue Service Advanced Configuration Snippet (Safety Valve) for hue_safety_valve.ini property and add a code snippet for each LDAP server. For example, for the server AD1.TEST.COM:
  5. Click Save Changes.
  6. Restart the Hue service.

LDAPS/StartTLS support

Secure communication with LDAP is provided using the TLS/SSL and StartTLS protocols. They allow Hue to validate the directory service it is going to converse with. Hence, if a Certificate Authority certificate file is provided, Hue will communicate using LDAPS. You can specify the path to the CA certificate under:
The StartTLS protocol can be used as well:

Troubleshooting LDAP Authentication Failures in Hue

The first step to diagnosing an LDAP issue is to run the ldapsearch command on the user or group that is involved in the authentication failure. The ldapsearch command gives you a snapshot of the state of the directory for a user or group. You can use the command to make sure the user or group has been configured as expected. The rest of this section will walk you through the Hue configuration required for some common deployment scenarios. Once you have made sure that hue.ini was configured properly, enable LDAP debugging to be able to audit LDAP actions in the Hue logs.

Hue Configuration for Common Deployment Scenarios

Hue Authentication against Active Directory using NT Domain



ldapsearch result for the username, sampleuser:
ldapsearch -x -LLL -H ldap://w2k12-ad1 -D "" -w Password1 -b "cn=users,dc=test,dc=com" "(&(objectclass=*)(sAMAccountName=sampleuser))"
dn: CN=Sample User,CN=Users,DC=TEST,DC=COM
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
cn: Sample User
sn: Sample
givenName: Sample
distinguishedName: CN=Sample User,CN=Users,DC=TEST,DC=COM
displayName: Sample User
uSNCreated: 12762
memberOf: CN=endusers,CN=Users,DC=TEST,DC=COM
memberOf: CN=admins,CN=Users,DC=TEST,DC=COM
memberOf: CN=Domain Admins,CN=Users,DC=TEST,DC=COM
name: Sample User
sAMAccountName: sampleuser
sAMAccountType: 805306368
userPrincipalName: sampleuser@TEST.COM
ldapsearch result for the group, samplegroup:
ldapsearch -x -LLL -H ldap://w2k12-ad1 -D "" -w Password1 -b "cn=users,dc=test,dc=com" "(&(objectclass=*)(cn=samplegroup))"
dn: CN=endusers,CN=Users,DC=TEST,DC=COM
objectClass: top
objectClass: group
cn: endusers
member: CN=Test User1,CN=Users,DC=TEST,DC=COM
member: CN=Sample User,CN=Users,DC=TEST,DC=COM
distinguishedName: CN=endusers,CN=Users,DC=TEST,DC=COM
sAMAccountName: endusers
sAMAccountType: 268435456
The following command returns a list of all member domains for group, samplegroup:
ldapsearch -x -LLL -H ldap://w2k12-ad1 -D "" -w Password1 -b "cn=users,dc=test,dc=com" "(&(objectclass=*)(cn=samplegroup))" member

dn: CN=endusers,CN=Users,DC=TEST,DC=COM
member: CN=Test User1,CN=Users,DC=TEST,DC=COM
member: CN=Sample User,CN=Users,DC=TEST,DC=COM

Hue Search Bind Authentication against an LDAP server

Make sure you have configured the ldap_url property to perform Search Bind Authentication against an LDAP server.
The ldapsearch result for sampleuser:
ldapsearch -x -LLL -H ldap:// -b "dc=test,dc=com" "(uid=sampleuser)"

dn: uid=sampleuser,ou=people,dc=test,dc=com
uid: sampleuser
displayName: Sample User
cn: Sample User
givenName: Sample
sn: User
initials: CH
homeDirectory: /home/sampleuser
loginShell: /bin/bash
gecos: Sample User,,,,
objectClass: inetOrgPerson
The ldapsearch result for group, samplegroup:
ldapsearch -x -LLL -H ldap:// -b "dc=test,dc=com" "(cn=samplegroup)"

dn: cn=admins,ou=people,dc=test,dc=com
objectClass: groupOfNames
cn: admins
description: Group of Names
member: uid=sampleuser,ou=people,dc=test,dc=com
member: uid=hue,ou=people,dc=test,dc=com
The following command returns a list of all member domains for group, samplegroup:
ldapsearch -x -LLL -H ldap:// -b "dc=test,dc=com" "(cn=samplegroup)" member

dn: cn=admins,ou=people,dc=test,dc=com
member: uid=sampleuser,ou=people,dc=test,dc=com
member: uid=hue,ou=people,dc=test,dc=com

Enabling LDAP Debugging in Hue

Once you have confirmed that the ldapsearch command works as expected, enable LDAP debugging in Hue to view Hue server logs in Cloudera Manager. Starting with CDH 5.4, you can view three different levels of LDAP actions in the Hue server logs. To enable debugging, set the following options in the [[ldap]] section of the hue.ini file:

  • debug - This enables python-ldap debugging. To enable, set to true.
  • debug_level - Sets the debug level of the underlying LDAP C library. Set to a value between 0 and 255.
  • trace_level - Sets the trace level for logging method calls. Set to a value between 0 and 9.

Enabling LDAP Debugging in Hue Using Cloudera Manager

  1. Go to the Hue Service > Configuration and click Advanced in the Category.
  2. Add the following after setting the values appropriately to the Hue Service Advanced Configuration Snippet (Safety Valve) for hue_safety_valve.ini
  3. Add the following to the Hue Service Environment Advanced Configuration Snippet (Safety Valve).
  4. Save and restart Hue. You should now be able to view LDAP actions in the following logs:
    • /var/log/hue/runcpserver.log
    • /var/run/cloudera-scm-agent/process/<id>-hue-HUE_SERVER/logs