Authenticate Hue Users with SAML

Hue supports SAML (Security Assertion Markup Language) for Single Sign-on (SSO) authentication.

The SAML 2.0 Web Browser SSO profile has three components:
  • User Agent - Browser that represents you, the user, seeking resources.
  • Service Provider (SP) - Service (Hue) that sends authentication requests to SAML.
  • Identity Provider (IdP) - SAML service that authenticates users.
When a user requests access to an application, the Service Provider (Hue) sends an authentication request from the User Agent (browser) to the Identity Provider. The Identity Provider authenticates the user, sends a response, and redirects the browser back to Hue (see graphic).

This page explains how to configure Hue, the Service Provider, and gives guidance on how to configure the Identity Provider, which differs per product.

Configure Hue for SAML Authentication

The Service Provider (Hue) and the Identity Provider use a metadata file to confirm each other's identity. Hue stores metadata from the SAML server, and the IdP stores metadata from Hue server.

Install and Configure IdP SAML Server

The instructions on this page assume that you have an Identity Provider set up and running. You can use any Identity Provider–Okta, Ping, OpenAM, and so on.

In Configure Hue at the Command Line (step 3), you must copy the metadata from your IdP's SAML server and store it in an XML file on every ost with a Hue server.

Configure Hue at the Command Line

  1. Install the following libraries on all hosts in your cluster:
    ## RHEL/CentOS
    yum install git gcc python-devel swig openssl
    ## Ubuntu/Debian
    apt-get install git gcc python-dev swig openssl
    ## SLES
    zypper install git gcc python-devel swig openssl make libxslt-devel libltdl-devel
  2. Install xmlsec1 and xmlsec1-openssl on all hosts in the cluster:
    ## RHEL/CentOS 
    yum install xmlsec1 xmlsec1-openssl
    ## Ubuntu/Debian
    apt-get install xmlsec1 libxmlsec1-openssl
    ## SLES (get latest version)
    tar -xvzf xmlsec1-1.2.24.tar.gz
    cd xmlsec1-1.2.24
    ./configure && make
    make install
  3. Copy metadata from your IdP's SAML server and save it as an XML file on every host with a Hue server.
    For example, if your Identity Provider is Shibboleth, visit https://<idp_host>:8443/idp/shibboleth, copy the metadata content, and paste it into an .xml file.
    mkdir -pm 755 /opt/cloudera/security/saml/
    cd /opt/cloudera/security/saml/
    vim idp-<your idp provider>-metadata.xml
    # Paste IdP SAML here and save
  4. Add key_file and cert_file for encrypted assertions–see Table of SAML Parameters.

Configure Hue in Cloudera Manager

Currently, all hue.ini properties for SAML must be added to Hue Service safety-valve in Cloudera Manager.
  1. Log on to Cloudera Manager and go to Hue > Configuration.
  2. Configure Hue Service Advanced Configuration Snippet (Safety Valve) for hue_safety_valve.ini with:
    ## Example Settings using Open AM:
    entity_id=<host base name>
  3. Click Save Changes, then select, Actions > Restart Hue.

Integrate IdP SAML Server with Hue

After Hue is configured and restarted, copy the metadata generated by Hue server and send it to your Identity Provider so they can configure the SAML server.

  1. Ensure Hue is configured, restarted, and running.
  2. Go to http://<hue_fqdn>:8889/saml2/metadata.
  3. Copy the metadata and send it to your Identity Provider.
  4. Ensure that your Identity Provider configures the SAML server with the Hue metadata (just as you configured the Hue server with SAML metadata).

SAML Properties in hue.ini

Table of SAML Parameters
SAML Parameter Description
authn_requests_signed Boolean, that when True, signs Hue-initiated authentication requests with X.509 certificate.
backend Hard-coded value set to SAML backend library packaged with Hue (libsaml.backend.SAML2Backend).
base_url URL that SAML Identity Provider uses for responses. Typically used in Load balanced Hue environments.
cert_file Path to X.509 certificate sent with encrypted metadata. File format must be .PEM.
create_users_on_login Boolean, that when True, creates users from OpenId, upon successful login.
entity_id Service provider ID. Can also accept pattern where '<base_url>' is replaced with server URL base.
key_file Path to private key used to encrypt metadata. File format must be .PEM.
key_file_password Password used to decrypt the X.509 certificate in memory.
logout_enabled Boolean, that when True, enables single logout.
logout_requests_signed Boolean, that when True, signs Hue-initiated logout requests with an X.509 certificate.
metadata_file Path to readable metadata XML file copied from Identity Provider.
name_id_format Format of NameID that Hue requests from SAML server.
optional_attributes Comma-separated list of optional attributes that Hue requests from Identity Provider.
required_attributes Comma-separated list of required attributes that Hue requests from Identity Provider. For example, uid and email.
redirect_whitelist Fully qualified domain name of SAML server: "^\/.*$,^https:\/\/<SAML_server_FQDN>\/.*$".
user_attribute_mapping Map of Identity Provider attributes to Hue django user attributes. For example, {'uid':'username', 'email':'email'}.
username_source Declares source of username as nameid or attributes.
xmlsec_binary Path to xmlsec_binary that signs, verifies, encrypts/decrypts SAML requests and assertions. Must be executable by user, hue.
Description of some properties to be set in hue.ini (via Cloudera Manager):
  • redirect_whitelist [desktop]
    Set to the fully qualified domain name of the SAML server so that Hue can redirect to the SAML server for authentication.
  • backend [desktop]>[[auth]]
    Point to the SAML backend (packaged with Hue):
  • xmlsec_binary [libsaml]
    Point to the xmlsec1 library path:
  • metadata_file [libsaml]
    Point to the path of the XML file you created from the IdP's metadata:
  • key_file and cert_file [libsaml]

    To encrypt communication between Hue and the Identity Provider, you need a private key and certificate. The private key signs requests sent to the Identity Provider and the certificate file encrypts and decrypts messages from the Identity Provider.

    Copy these files from the Identity Provider and set key_file and cert_file to their respective paths. Both files are in PEM format and must be named with the .PEM extension.

    Users with password-protected certificates can set the property, key_file_password in hue.ini. Hue uses the password to decrypt the SAML certificate in memory and passes it to xmlsec1 through a named pipe. The decrypted certificate never touches the disk. This only works for POSIX-compatible platforms.


Remember to Enable DEBUG for logging.


OpenSSL might fail in CDH 5.5.x and higher with this message:
SSLError: [Errno bad handshake] [('SSL routines', 'SSL3_CHECK_CERT_AND_ALGORITHM', 'dh key too small')]
To resolve, append the following code to the file, /usr/java/<your_jdk_version>-cloudera/jre/lib/security/
jdk.tls.disabledAlgorithms=MD5, RC4, DH

SAML Decrypt Error

The following error is an indication that you are using a slightly different SAML protocol from what Hue expects:
Error: ('failed to decrypt', -1)
To resolve:
  1. Download and rename Python script, fix-xmlsec1.txt.
    wget -O
  2. Change permissions as appropriate, for example:
    chmod 755
  3. In hue.ini, set xmlsec_binary=<path_to_script>/
  4. Run

This script repairs the known issue whereby xmlsec1 is not compiled with RetrievalMethod and cannot find the location of the encrypted key. SAML2 responses would sometimes place EncryptedKey outside of the EncryptedData tree. This script moves EncryptedKey under EncryptedData.