Authenticate Hue with LDAP

Configuring Hue for Lightweight Directory Access Protocol (LDAP) lets you import users and groups from a directory service, synchronize group membership manually or at automatically login, and authenticate with LDAP.

This page explains how to configure Hue for LDAP authentication. To import users and group from LDAP, see Synchronize Hue with LDAP.

Authenticate Hue Users and Groups with LDAP

Hue supports Active Directory (AD) and open standard LDAP such as OpenLDAP and OpenDJ.

There are two ways to bind Hue with an LDAP directory service:

  • Search Bind: Hue searches for user credentials with search base (and attribute and filter).
  • Direct Bind: Hue authenticates (without searching) in one of two ways:
    • NT Domain: Bind to Microsoft Active Directory with username@domain (the UPN)or
    • Username Pattern: Bind to open standard LDAP with full path of directory information tree (DIT).

Encryption: To prevent credentials from transmitting in the clear, encrypt with LDAP over SSL, using the LDAPS protocol on the LDAPS port (636 by default); or encrypt with the StartTLS extension using the standard LDAP protocol and port (389 by default). Cloudera recommends LDAPS. You must have a CA Certificate in either case.

Hue Supported LDAP Authentication and Encryption Methods
LDAP Auth Action Encrypted (LDAPS) Encrypted (LDAP+TLS) Not Encrypted (LDAP)
Search Bind AD, LDAP AD, LDAP AD, LDAP
Direct Bind - NT Domain AD AD AD
Direct Bind - User Pattern LDAP LDAP LDAP

Prerequisites

To authenticate Hue with LDAP, you must have:
  • LDAP server
  • Bind account (or support for anonymous binds)
  • Cloudera Manager account with Full Administrator permissions
  • [optional] LDAP server with LDAPS or StartTLS encryption.

Search Bind

Search bind authentication does an ldapsearch against one or more directory services and binds with the found distinguished name (DN) and password. Hue searches the subtree from the base distinguished name. If LDAP Username Attribute is set, Hue looks for an entry whose attribute has the same value as the short name given at login.
Video: Authenticate Hue with LDAP and Search Bind
  1. Log on to Cloudera Manager and click Hue.
  2. Click the Configuration tab and filter by scope=Service-wide and category=Security.
  3. Set the following required properties:
    Authentication Backend desktop.auth.backend.LdapBackend
    LDAP URL ldaps://<ldap_server>:636 (or ldap://<ldap_server>:389)
    LDAP Server CA Certificate /path_to_certificate/cert.pem
    LDAP Search Base DC=mycompany,DC=com
    LDAP Bind User Distinguished Name username@domain
    LDAP Bind Password bind_user_password
    Use Search Bind Authentication TRUE
    Enable LDAP TLS FALSE if using LDAPS or not encrypting
    Create LDAP users on login TRUE
  4. You can optionally improve search performance with attributes and filters.
    LDAP User Filter objectclass=user (default = *)
    LDAP Username Attribute sAMAccountName (AD default), uid (LDAP default)
    LDAP Group Filter objectclass=group (default = *)
    LDAP Group Name Attribute cn (default)
    LDAP Group Membership Attribute member (default)
  5. Add any valid user and/or valid group to quickly test your LDAP configuration.
    LDAP Username for Test LDAP Configuration Any valid user
    LDAP Group Name for Test LDAP Configuration Any valid group
  6. Click Save Changes.
  7. Test your LDAP configuration, and when successful, Restart Hue.
## You can test ldapsearch at the command line as follows: 
LDAPTLS_CACERT=/<path_to_cert>/<ca_certificate> ldapsearch -H ldaps://<ldap_server>:636 \
-D "<bind_dn>" -w <bind_password> -b <base_dn> "samaccountname=<user>"

Direct Bind

To authenticate with direct binding, Hue needs either the User Principal Name (UPN) for Active Directory, or the full path to the LDAP user in the Directory Information Tree (DIT) for open standard LDAP.
Video: Authenticate Hue with LDAP and Direct Bind
To directly bind to an Active Directory/LDAP server with NT domain:
  1. Log on to Cloudera Manager and click Hue.
  2. Click the Configuration tab and filter by scope=Service-wide and category=Security.
  3. Set LDAP properties exactly like Search Bind with these exceptions:
    Active Directory Domain <your NT domain>
    LDAP Bind User Distinguished Name <username only> (not username@domain)
    Use Search Bind Authentication FALSE
  4. Click Save Changes.
  5. Test your LDAP configuration, and when successful, Restart Hue.
To directly bind to an open standard LDAP server with a username pattern:
  1. Remove the value for Active Directory Domain.
  2. Set both LDAP Username Pattern and LDAP Bind User Distinguished Name to a DN string that represents the full path of the directory information tree, from UID to top level domain.

Test Hue LDAP Configuration On-the-Fly

You can test your LDAP settings without restarting the Hue service-simply input values and save changes.
  1. Configure Hue LDAP Search Bind or Direct Bind.
  2. Add a user and group name for Test LDAP Configuration.
  3. Click Save Changes.
  4. Select Actions > Test LDAP Configuration.
  5. Click Test LDAP Configuration.
  6. Restart Hue when the test succeeds and log on to the Hue Web UI.


Unmanaged Clusters

Consumers with unmanaged clusters (that is, without Cloudera Manager) must manually set properties in hue.ini. Consumers with managed clusters must use Cloudera Manager to set properties in hue.ini.

Example of a Search Bind configuration encrypted with LDAPS: 
[[custom]]
[[auth]]
backend=desktop.auth.backend.LdapBackend

[[ldap]]
ldap_url=ldaps://w2k8-1.ad.sec.cloudera.com:636
search_bind_authentication=true
ldap_cert=/<path_to_cacert>/w2k8-1-root.pem
use_start_tls=false
create_users_on_login=true
base_dn="DC=ad,DC=sec,DC=cloudera,DC=com"
bind_dn="<username>@ad.sec.cloudera.com"
bind_password_script=<path_to_password_script>/<script.sh>
test_ldap_user="testuser1"
test_ldap_group="testgroup1"

[[[users]]]
user_filter="objectclass=user"
user_name_attr="sAMAccountName"

[[[groups]]]
group_filter="objectclass=group"
group_name_attr="cn"
group_member_attr="member"
Example of a Direct Bind configuration for Active Directory encrypted with LDAPS: 
[[ldap]]
ldap_url=ldaps://w2k8-1.ad.sec.cloudera.com:636
search_bind_authentication=false
nt_domain=ad.sec.cloudera.com
ldap_cert=/<path_to_cacert>/w2k8-1-root.pem
use_start_tls=false
create_users_on_login=true
base_dn="DC=ad,DC=sec,DC=cloudera,DC=com"
bind_dn="<username>"
bind_password_script=<path_to_password_script>/<script.sh>
...
Example of a Direct Bind configuration for Active Directory encrypted with StartTLS: 
[[ldap]]
ldap_url=ldap://w2k8-1.ad.sec.cloudera.com:389
search_bind_authentication=false
nt_domain=ad.sec.cloudera.com
ldap_cert=/opt/cloudera/security/cacerts/w2k8-1-root.pem
use_start_tls=true
create_users_on_login=true
base_dn="DC=ad,DC=sec,DC=cloudera,DC=com"
bind_dn="cconner"
bind_password_script=<path_to_password_script>/<script.sh>
...

Table of Hue LDAP Properties

Property Name Description and Syntax
General Hue LDAP Properties
Authentication Backend

backend

Authentication Mode. Select desktop.auth.backend.LdapBackend.

Multiple backends are allowed. Create a list and add it to the Hue safety-valve.
LDAP URL

ldap_url

URL for the LDAP server.

Syntax: ldaps://<ldap_server>:<636> or ldap://<ldap_server>:<389>

Important: To prevent usernames and passwords from transmitting in the clear, use ldaps:// or ldap:// + "Enable LDAP TLS".
Create LDAP users on login

create_users_on_login

Flag to create new LDAP users at Hue login.

If true, any user who logs into Hue is automatically created. If false, only users that exist in useradmin can log in.
Direct Bind Properties
Active Directory Domain

nt_domain

For direct binding with Active Directory only. Typically maps to the user email address or ID in conjunction with the domain. Allows Hue to authenticate without having to follow LDAP references to other partitions. Hue binds with User Principal Names (UPNs) if provided.

Example: ad.<mycompany>.com

Important: Do not use nt_domain when binding with a username pattern or if using search bind.
LDAP Username Pattern

ldap_username_pattern

For direct binding with LDAP (non-Active Directory) only (because AD uses UPNs which have a space in them).

Username Pattern finds the user attempting to login into LDAP by adding the username to a predefined DN string. Use <username> to reference the user logging in. An example is "uid=<username>,ou=people,dc=mycompany,dc=com".
Search Bind Properties
Use Search Bind Authentication

search_bind_authentication

 Flag to enable/disable search binding.
LDAP Search Base

base_dn

Distinguished name to use as a search base for finding users and groups.

Syntax: dc=ad, dc=sec, dc=mycompany,dc=com
Encryption Properties
LDAP Server CA Certificate

ldap_cert

Full path to .pem file with Certificate Authority (CA) chain used to sign the LDAP server certificate.

If left blank, all certificates are trusted and otherwise encrypted usernames and passwords are vulnerable to attack.
Enable LDAP TLS

use_start_tls

 Flag to enable/disable encryption with StartTLS.
Import / Sync Properties
LDAP Bind User Distinguished Name

bind_dn

Bind user. Only use if LDAP/AD does not support anonymous binds. (Typically, LDAP supports anonymous binds and AD does not.) Bind User differs per auth type:

  • Search Bind: username@domain
  • Direct Bind with NT Domain: username
  • Direct Bind with Username Pattern: DN string (and same as LDAP Username Pattern)
LDAP Bind Password

bind_password

 Bind user password.
Filter Properties
LDAP User Filter

user_filter

 General LDAP filter to restrict search of valid users. Only used by Search Bind authentication and LDAP Sync.

The default is objectclass=* but can differ. For example, some LDAP environments support Posix objects for *nix authentication and the user filter might need to be objectclass=posixAccount.
LDAP Username Attribute

user_name_attr

 Username to search against (the attribute in LDAP that contains the username).

Typical attributes include sAMAccountName (default for AD/LDAP) and uid (LDAP default).

Maintain case sensitivity when setting attributes for AD/LDAP.
LDAP Group Filter

group_filter

 General LDAP filter to restrict search of valid groups. Only used by LDAP Sync (not authentication). If left blank, no filtering is used and all groups in LDAP are synced.

The default is objectclass=* but can differ. For example, some LDAP environments support Posix objects for *nix authentication and the user filter might need to be objectclass=posixGroup.
LDAP Group Name Attribute

group_name_attr

Group name to search against (the attribute in LDAP that contains the groupname).

If left blank, the default is "cn" (common name), that typically works with AD/LDAP.

Maintain case sensitivity when setting attributes for AD/LDAP.
LDAP Group Membership Attribute

group_member_attr

Attribute in the group that contains DNs of all the members.(Optional) -

If left blank, the default is "memberOf" or "member", that typically works with Active Directory/LDAP.
Test Properties
LDAP Username for Test LDAP Configuration

test_ldap_user

 Any user (ideally with low privileges) used to verify the LDAP configuration.
LDAP Group Name for Test LDAP Configuration

test_ldap_group

 Any group (and not necessarily one that includes the test user) used to verify the LDAP configuration.