This is the documentation for CDH 5.0.x. Documentation for other versions is available at Cloudera Documentation.

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, SAML2 and so on. This topic details how you can configure Hue to authenticate against an LDAP directory server.

When authenticating via LDAP, Hue validates login credentials against an LDAP directory service if configured with the LDAP authentication backend:
[desktop]
[[auth]]
backend=desktop.auth.backend.LdapBackend
The LDAP authentication backend will automatically create users that don’t exist in Hue by default. Hue needs to import users in order to properly perform the authentication. Passwords are never imported when importing users. If you want to disable automatic import set the create_users_on_login property under the [desktop] > [[ldap]] section of hue.ini to false.
[desktop]
[[ldap]]
create_users_on_login=false
The 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:

You can specify the authentication mechanism using the search_bind_authentication property under the [desktop] > [[ldap]] section of 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

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

Default: "objectclass=*"
user_name_attr The attribute that will be considered the username to be searched against. Typical attributes to search for include: uid, sAMAccountName.

Default: sAMAccountName
With the above configuration, the LDAP search filter will take on the form:
(&(objectClass=*)(sAMAccountName=<user entered usename>))
  Important: Setting search_bind_authentication=true in hue.ini tells Hue to perform an LDAP search using the bind credentials specified for the bind_dn and bind_password configuration properties. Hue will start searching the subtree starting from the base DN specified for the base_dn property. It will then search the base DN for an entry whose attribute, specified in user_name_attr, has the same value as the short name provided on login. The search filter, defined in user_filter will also be used to limit the search.

Direct Bind

The direct bind mechanism for authenticating will bind to the LDAP server using the username and password provided at login.

The following configuration properties can be used to determine how Hue binds to the LDAP server. These can be set under the [desktop] > [[ldap]] section of hue.ini.
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.

Default: mycompany.com
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.

Default: "uid=<username>,ou=People,dc=mycompany,dc=com"
  Important: Setting search_bind_authentication=false in hue.ini tells Hue to perform a direct bind to LDAP using the credentials provided (not bind_dn and bind_password specified in hue.ini). There are two ways direct bind works depending on whether the nt_domain property is specified in hue.ini:
  • nt_domain is specified: This is used to connect to an Active Directory service. In this case, the User Principal Name (UPN) is used to perform a direct bind. Hue forms the UPN by concatenating the short name provided at login with the nt_domain. For example, <short name>@<nt_domain>. The ldap_username_pattern property is ignored.
  • nt_domain is not specified: This is used to connect to all other directory services (can handle Active Directory, but nt_domain is the preferred way for AD). In this case, ldap_username_pattern is used and it should take on the form cn=<username>,dc=example,dc=com where <username> 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 via 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.
  Important: When managing LDAP entries, the User Admin app will always perform an LDAP search and will always use bind_dn, bind_password, base_dn, as defined in hue.ini.

Synchronizing LDAP Users and Groups

Users and groups can be synchronized with the directory service via the User Admin interface or via 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.

  Note: Users that have been deleted from the directory service will not be deleted from Hue. Those users can be manually deactivated from Hue via the User Admin interface.

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

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

LDAPS/StartTLS support

Secure communication with LDAP is provided using the SSL/TLS 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 : 
[desktop]
    [[ldap]]
    ldap_cert=/etc/hue/ca.crt
The StartTLS protocol can be used as well:
[desktop]
    [[ldap]]
    use_start_tls=true
Page generated September 3, 2015.