Configuring Hue for SAML

This section describes the configuration required to use Hue with SAML 2.0 (Security Assertion Markup Language) for single sign-on (SSO) authentication.

The SAML 2.0 Web Browser SSO profile has three components: a Service Provider, a User Agent and an Identity Provider. In this case, Hue is the Service Provider (SP), you can use an Identity Provider (IdP) of your choice, and your browser, representing you, the user, is the User Agent. When a user requests access to an application, Hue sends an authentication request from the browser to the Identity Provider which then authenticates the user and redirects the browser back to Hue.

Prerequisites

The instructions on this page assume that you have an Identity Provider set up and running. This blog post guides users through setting up SSO with Hue, using the SAML backend and Shibboleth as the Identity Provider.

Step 1: Install git, gcc, python-devel, swig, and openssl packages

For example, on RHEL systems, use the following commands:

yum install git gcc python-devel swig openssl

Step 2: 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. First, install the xmlsec1 package on your system.

RHEL, CentOS and SLES:

For RHEL, CentOS and SLES systems, the xmlsec1 package is available for download from the EPEL repository. To install packages from the EPEL repository, first download the appropriate the RPM package to your machine, substituting the version in the package URL with the one required for your system. For example, use the following commands for CentOS 5 or RHEL 5: 
rpm -Uvh http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm 
yum install xmlsec1
yum install xmlsec1-openssl

Oracle Linux:

For Oracle Linux systems, download the xmlsec1 package from http://www.aleksey.com/xmlsec/ and execute the following commands: 
tar -xvzf xmlsec1-<version>.tar.gz
cd xmlsec1-<version>
./configure && make
sudo make install

You should now be able to install djangosaml and pysaml2 on your machines.

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 3: Update the Hue configuration file

To enable support for SAML, update the necessary parameters in Hue's configuration file, hue.ini. This table lists the available SAML parameters in hue.ini under the section, [libsaml].

Parameter

 Description
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.
create_users_on_login Boolean, that when True, creates users from OpenId, upon successful login.
required_attributes Comma-separated list of attributes that Hue requests from the Identity Provider. For example, uid, email, and so on.
optional_attributes Comma-separated list of optional attributes that Hue requests from the Identity Provider.
metadata_file Path to the Identity Provider metadata that you copy to a local file. This file should be readable.
key_file Path to the private key used to encrypt the metadata. File format .PEM
cert_file Path to the X.509 certificate to be sent along with the encrypted metadata. File format .PEM
user_attribute_mapping Map of Identity Provider attributes to Hue django user attributes. For example, {'uid':'username', 'email':'email'}.
logout_requests_signed Boolean, that when True, signs Hue-initiated logout requests and provides a certificate.
For non-parcel based deployments, 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 the SAML server for authentication. This is not required if you are using a CDH parcel-based deployment managed by Cloudera Manager.
redirect_whitelist Value: "^\/.$,^https:\/\/<fqdn_of_SAML_server>\/.$"

Step 3a: Update the SAML Metadata file

Update the metadata file pointed to by your Hue configuration file, hue.ini. Check your Identity Provider documentation for details on how to procure the XML metadata and paste it into the <metadata_file_name>.xml file at the location specified by the configuration parameter metadata_file.

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

Step 3b: Configure Paths to the Private key and Certificate

To enable communication between Hue and the Identity Provider, set key_file to the path of the private key and cert_pem to the path of the certificate file. The private key signs requests sent to the Identity Provider and the certificate file encrypts and decrypts messages from the Identity Provider.

Step 3c: Configure Hue to use SAML Backend

For SAML to allow user logins and create users, update the backend configuration property in hue.ini to use the SAML authentication backend. The backend property is in the [[auth]] sub-section under [desktop]. 
backend=libsaml.backend.SAML2Backend
Here is an example configuration of the [libsaml] section from hue.ini. 
xmlsec_binary=/usr/local/bin/xmlsec1
create_users_on_login=true
metadata_file=/etc/hue/saml/metadata.xml
key_file=/etc/hue/saml/key.pem
cert_file=/etc/hue/saml/cert.pem
logout_requests_signed=true

Step 4: Restart the Hue server

Use the following command to restart the Hue server.

sudo service hue restart

Troubleshooting

  • SSLError: 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
  • Failed to decrypt: 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: download and run this Python script, fix-xmlsec.py and set xmlsec_binary=<path to script/fix-xmlsec.py> in hue.ini.

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