Configuring Hue for SAML

This page explains how to configure Hue to work with 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, Hue sends an authentication request from the browser to the Identity Provider. The Identity Provider authenticates the user, sends a response, and redirects the browser back to Hue. You can use any Identity Provider (such as Shibboleth) .

Summary Steps for Configuring Hue with SAML

Prerequisite: Ensure you have an Identify Provider (such as Shibboleth) configured before starting.

Install Libraries
  • Step 1: Install git, gcc, python-devel, swig and openssl.
  • Step 2: Install xmlsec1 and xmlsec1-openssl and disable cipher algorithms.
  • Step 3: Install djangosaml and pysaml2.
Configure Hue
  • Step 4: Copy metadata from your Identity Provider's SAML server and save it in an XML file.
  • Step 5: Configure Hue to work with SAML (in hue.ini) and restart the Hue server.
Configure SAML
  • Step 6: Copy metadata from the Hue server and send it to the Identity Provider.

Detailed Steps for Configuring Hue with SAML

Prerequisite

The instructions on this page assume that you have an Identity Provider set up and running.

See the upstream Hue blog post, SSO with Hue: new SAML backend, for a demo on configuring Hue for single sign-on (SSO) authentication with SAML 2.0 on the backend and Shibboleth as the Identity Provider.

Step 1: Install swig and openssl packages

  1. Install git, gcc, python-devel, swig and openssl. Use yum for RHEL/CentOS/OLES and zypper for SLES: 
    <package manager> install git gcc python-devel swig openssl
  2. [CDH 5.5.x and higher] Disable the cipher algorithms, MD5, RC4, and DH by appending the following code to the file, /usr/java/<your_jdk_version>-cloudera/jre/lib/security/java.security: 
    jdk.tls.disabledAlgorithms=MD5, RC4, DH
    See Troubleshooting below.

Step 2: Install xmlsec1 and xmlsec1-openssl packages

Red Hat Enterprise Linux (RHEL, CentOS) and Oracle oraLinux (OL):

  1. Download and install the EPEL repository to get the xmlsec1 package:
    • RHEL/CentOs/OEL 7: 
      wget http://dl.fedoraproject.org/pub/epel/7/x86_64/e/epel-release-7-6.noarch.rpm
rpm -ivh epel-release-7-6.noarch.rpm
    • RHEL/CentOs/OEL 6: 
      wget http://download.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
rpm -ivh epel-release-6-8.noarch.rpm
    • RHEL/CentOs/OEL 5: 
      wget http://download.fedoraproject.org/pub/epel/5/x86_64/epel-release-5-4.noarch.rpm
rpm -ivh epel-release-5-4.noarch.rpm
  2. Install xmlsec1 and xmlsec1-openssl: 
    yum install xmlsec1 xmlsec1-openssl

SUSE Linux Enterprise Server (SLES):

Download the xmlsec1 package from http://www.aleksey.com/xmlsec/ and install: 
wget http://www.aleksey.com/xmlsec/download/xmlsec1-<version>.tar.gz
tar -xvzf xmlsec1-<version>.tar.gz
cd xmlsec1-<version>
./configure && make
sudo make install

Step 3: Install djangosaml and pysaml2 libraries

The libraries, djangosaml2 and pysaml2, support SAML in Hue. They depend on the xmlsec1 package to be installed and executable by the user, hue. 
build/env/bin/pip install -e git+https://github.com/abec/pysaml2@HEAD#egg=pysaml2
build/env/bin/pip install -e git+https://github.com/abec/djangosaml2@HEAD#egg=djangosaml2

Step 4: Copy Metadata from the SAML Server into an XML File

The Service Provider (Hue) and the Identity Provider (SAML) use a metadata file to confirm each other's veracity. Hue stores metadata from the SAML server, and SAML stores metadata from Hue server (see Step 6: Configure SAML).

Read the documentation of your Identity Provider for details on how to procure the XML metadata of the SAML server. Paste the metadata into an XML file. When configuring Hue, set the property, metadata_file, to the path of this file.

For example, if your Identity Provider is Shibboleth, visit https://<identity_provider_host>:8443/idp/shibboleth, copy the metadata content, and paste it into the Hue metadata file.

Step 5: Configure Hue and Restart the Hue Server

To enable support for SAML, configure Hue with the necessary SAML parameters and values.

Users with unmanaged CDH deployments must manually edit /etc/hue/conf/hue.ini and restart the hue service: 
sudo service hue restart

Users with managed CDH deployments must set these parameters in Cloudera Manager:

  1. Go to the Hue service and click on the Configuration tab.
  2. Filter by Scope > HUE-n (Service-Wide) and Category > Advanced.
  3. Locate the property, Hue Service Advanced Configuration Snippet (Safety Valve) for hue_safety_valve.ini.
  4. Input your SAML properties and values in the edit box. See the SAML configuration example below.
  5. Click Save Changes.
  6. Select Actions > Restart to restart the Hue service (which also restarts the Hue server).
Example of a SAML configuration in hue.ini:
[desktop]
redirect_whitelist="^\/.*$,^https:\/\/saml.example.com\/.*$"
[[auth]]
backend=libsaml.backend.SAML2Backend

[libsaml]
xmlsec_binary=/usr/bin/xmlsec1
metadata_file=/opt/cloudera/security/saml/idp-metadata.xml
key_file=/opt/cloudera/security/saml/idp.key
cert_file=/opt/cloudera/security/saml/idp.crt
username_source=nameid
name_id_format="urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified"
entity_id=hueserver1
#user_attribute_mapping='{"mail":"username","uid":"uid"}'
#required_attributes='["uid", "mail"]'
#base_url=https://hue.example.com:8888
#authn_requests_signed=true
#logout_enabled=true
#logout_requests_signed=true
SAML parameters in /etc/hue/conf/hue.ini under the sections, [desktop] and [libsaml]
SAML Parameter Description
authn_requests_signed Boolean, that when True, signs Hue-initiated authentication requests with an X.509 certificate.
backend Hard-coded value set to the SAML backend library packaged with Hue (libsaml.backend.SAML2Backend).
base_url URL that the SAML Identity Provider uses for responses. Typically used in Load balanced Hue environments.
cert_file Path to the X.509 certificate to be sent along with the 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 a pattern where '<base_url>' is replaced with the server URL base.
key_file Path to the private key used to encrypt the 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 the readable metadata XML file that you copy from Identity Provider.
name_id_format The format of the NameID that Hue requests from the SAML server.
optional_attributes Comma-separated list of optional attributes that Hue requests from the Identity Provider.
required_attributes Comma-separated list of attributes that Hue requests from the Identity Provider. For example, uid and email.
redirect_whitelist Fully qualified domain name of the 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 Determines if username should be deremined from nameid or attributes.
xmlsec_binary Path to the xmlsec_binary, an executable to sign, verify, encrypt, and decrypt SAML requests and assertions. It must be executable by the user, hue.
  • redirect_whitelist:

    Hue uses the property, redirect_whitelist, to protect itself from redirecting to unapproved URLs.

    Set the parameter, redirect_whitelist, in the [desktop] section of hue.ini, to the fully qualified domain name of the SAML server so that Hue can redirect to the SAML server for authentication. 
    redirect_whitelist=^\/.$,^https:\/\/<SAML_server_fully_qualified_domain_name>\/.$
  • backend
    Point the property, backend, to the SAML backend (packaged with Hue). The backend property is in hue.ini under [desktop] > [[auth]] and should be configured as follows: 
    backend=libsaml.backend.SAML2Backend
  • xmlsec_binary
    Find the path to the XML Security (xmlsec) library that you installed in Step 2: 
    which xmlsec1
    Point the parameter, xmlsec_binary, to the xmlsec1 path: 
    xmlsec_binary=/usr/bin/xmlsec1
  • metadata_file
    In Step 3, you created an XML file with metadata from your Identity Provider. Point the parameter, metadata_file, to the path of that file: 
    metadata_file=/path/to/<your_idp_metadata_file>.xml
  • key_file and cert_file

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

Step 6: Configure SAML

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>:8888/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).

Troubleshooting

To enable DEBUG messages for all the logs in the directory, /var/log/hue, choose one of these methods:
  • In the Hue Web UI, go to the Home page, select Server Logs, and check the box by Force Debug Level. Debug is enabled on-the-fly.
  • In Cloudera Manager, go to Hue > Configuration, search for and set Enable Django Debug Mode, click Save Changes, and Restart the Hue service.
  • At the command line, open /etc/hue/conf/hue.ini, scroll to [desktop], and set django_debug_mode=true. Restart the Hue service: 
    sudo service hue restart

SAML SSL Error

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/java.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 http://www.cloudera.com/documentation/other/shared/fix-xmlsec1.txt -O fix-xmlsec1.py
  2. Change permissions as appropriate, for example: 
    chmod 755 fix-xmlsec1.py
  3. In hue.ini, set xmlsec_binary=<path_to_script>/fix-xmlsec1.py.
  4. Run fix-xmlsec1.py.

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.