Integrating Hue with LDAP
When Hue is integrated with LDAP users can use their existing credentials to authenticate and inherit their existing groups transparently. There is no need to save or duplicate any employee password in Hue. There are several other ways to authenticate with Hue such as PAM, SPNEGO, OpenID, OAuth, and SAML2. This topic details how you can configure Hue to authenticate against an LDAP directory server.
[desktop] [[auth]] backend=desktop.auth.backend.LdapBackend
[desktop] [[ldap]] create_users_on_login=falseThe purpose of disabling the automatic import is to allow only a predefined list of manually imported users to login.
There are two ways to authenticate with a directory service through Hue:
|search_bind_authentication||Uses search bind authentication by default. Set this property to false to use direct bind authentication.
Search BindThe search bind mechanism for authenticating will perform an ldapsearch against the directory service and bind using the found distinguished name (DN) and password provided. This is the default method of authentication used by Hue with LDAP.
The following configuration properties under the [desktop] > [[ldap]] > [[[users]]] section in hue.ini can be set to restrict the search process.
|user_filter||General LDAP filter to restrict the search.
|user_name_attr||The attribute that will be considered the username to be searched against. Typical attributes to search for include: uid, sAMAccountName.
(&(objectClass=*)(sAMAccountName=<user entered username>))
The direct bind mechanism for authenticating will bind to the LDAP server using the username and password provided at login.
|nt_domain||The NT domain to connect to (only for use with Active Directory). This AD-specific property allows Hue to authenticate with AD without having
to follow LDAP references to other partitions. This typically maps to the email address of the user or the user's ID in conjunction with the domain.
If provided, Hue will use User Principal Names (UPNs) to bind to the LDAP service.
|ldap_username_pattern||Provides a template for the DN that will ultimately be sent to the directory service when authenticating. The <username> parameter will be replaced with the username provided at login.
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 will perform an LDAP search using the same methods and configurations as described above. That is, Hue will take the provided username and create 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 will 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 will in fact be synchronized instead. In the case of importing users for a particular group, new users will be imported and existing users will be 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 will be 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.
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:
- Go to the Hue Service.
- Click Configuration.
- Select .
- 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:
[desktop] [[ldap]] [[[ldap_servers]]] [[[[AD1.TEST.COM]]]] ldap_url=ldap://w2k8-ad1 search_bind_authentication=true create_users_on_login=true base_dn="cn=users,dc=ad1,dc=test,dc=com" bind_dn="cn=Administrator,cn=users,dc=ad1,dc=test,dc=com" bind_password="Password1" [[[[AD2.TEST.COM]]]] ldap_url=ldap://w2k8-ad2 search_bind_authentication=true create_users_on_login=true base_dn="cn=users,dc=ad2,dc=test,dc=com" bind_dn="cn=Administrator,cn=users,dc=ad2,dc=test,dc=com" bind_password="Password1"
- Click Save Changes.
- Restart the Hue service.
[desktop] [[ldap]] ldap_cert=/etc/hue/ca.crt
[desktop] [[ldap]] use_start_tls=true
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
[[ldap]] ldap_url=ldap://w2k12-ad1 nt_domain=test.com base_dn="cn=users,dc=test,dc=com" bind_dn="Administrator@test.com" bind_password="Password1" [[[users]]] user_name_attr=sAMAccountName user_filter="objectclass=*" [[[groups]]] group_name_attr=cn group_filter="objectclass=*"
ldapsearch -x -LLL -H ldap://w2k12-ad1 -D "Administrator@test.com" -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 -x -LLL -H ldap://w2k12-ad1 -D "Administrator@test.com" -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 ......
ldapsearch -x -LLL -H ldap://w2k12-ad1 -D "Administrator@test.com" -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
[[ldap]] ldap_url=ldap://ldap.test.com base_dn="dc=test,dc=com"The ldapsearch result for sampleuser:
ldapsearch -x -LLL -H ldap://ldap.test.com -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 mail: email@example.com homeDirectory: /home/sampleuser loginShell: /bin/bash gecos: Sample User,,,, objectClass: inetOrgPerson
ldapsearch -x -LLL -H ldap://ldap.test.com -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
ldapsearch -x -LLL -H ldap://ldap.test.com -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
- Go to the Hue Service > Configuration and click Advanced in the Category.
- Add the following after setting the values appropriately to the Hue Service Advanced Configuration Snippet (Safety Valve) for hue_safety_valve.ini
[desktop] [[ldap]] debug=true debug_level=255 trace_level=9
- Add the following to the Hue Service Environment Advanced Configuration Snippet (Safety Valve).
- Save and restart Hue. You should now be able to view LDAP actions in the following logs: