Configuring Hue for SAML

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

Continue reading:

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
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.
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_requests_signed Boolean, that when True, signs Hue-initiated logout requests with an X.509 certificate.
metadata_file Path to the Identity Provider metadata that you copy to a readable local file.
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, email, and so on.
user_attribute_mapping Map of Identity Provider attributes to Hue django user attributes. For example, {'uid':'username', 'email':'email'}.
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.
For deployments that do not use parcels, 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>\/.$"
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 3a: Update the SAML Metadata file

Update the metadata file pointed to by the property, metadata_file, in hue.ini. The metadata file is used by the Service and Identity providers to confirm the veracity of each other (as opposed to the user).

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, 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, specify two properties in hue.ini: set key_file to the path of the private key and cert_file to the path of the certificate file. Both files must be in the .PEM format. The private key signs requests sent to the Identity Provider and the certificate file encrypts and decrypts messages from the Identity Provider.

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 3c: Configure Hue to use SAML Backend

Configure the property, backend, to use the SAML authentication backend and allow user logins and create users. The backend property is in hue.ini under [desktop] > [[auth]]. 
backend=libsaml.backend.SAML2Backend

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