This is the documentation for CDH 5.0.x. Documentation for other versions is available at Cloudera Documentation.

Configuring Hue for SAML

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

The SAML 2.0 Web Browser SSO profile has three components: a Security 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 you are the user acting through your browser (User Agent). When a user requests access to an application, Hue uses your browser to send an authentication request to the Identity Provider which then authenticates the user and redirects them back to Hue .

This blog post guides users through setting up SSO with Hue, using the SAML backend and Shibboleth as the Identity Provider.

Note: The following instructions assume you already have an Identity Provider set up and running.

Step 1: Install swig and openssl packages

Install swig and openssl. For example, on RHEL systems, use the following commands:

yum install swig

yum install openssl

Step 2: Install libraries to support SAML in Hue

Install the djangosaml2 and pysaml2 libraries to support SAML in Hue. These libraries are dependent on the xmlsec1 package to be installed and available on the machine for Hue to use. Follow these instructions to 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. For example, on CentOS, use the following commands to install the package, substituting the version in the package URL with the one required for your system:

rpm -Uvh http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm
yum install xmlsec1

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

Important: The xmlsec1 package must be executable by the user running Hue.

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

Several configuration parameters need to be updated in Hue's configuration file, hue.ini to enable support for SAML. The table given below describes the available parameters for SAML in hue.ini under the [libsaml] section.

Parameter	Description
`xmlsec_binary`	This is a path to the `xmlsec_binary`, an executable used to sign, verify, encrypt and decrypt SAML requests and assertions. This program should be executable by the user running Hue.
`create_users_on_login`	Create Hue users received in assertion response upon successful login. The value for this parameter can be either "true" or "false".
`required_attributes`	Attributes Hue asks for from the IdP. This is a comma-separated list of attributes. For example, `uid`, `email` and so on.
`optional_attributes`	Optional attributes Hue can ask for from the IdP. Also a comma-separated list of attributes.
`metadata_file`	This is a path to the IdP metadata copied 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`	Mapping from attributes received from the IdP to the Hue's django user attributes. For example, {'uid':'username', 'email':'email'}.
`logout_requests_signed`	Have Hue initiated logout requests be signed and provide a certificate.

Step 3a: Update the SAML metadata file

Update the metadata file pointed to by your Hue configuration file, hue.ini. Check your IdP 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 you were using the Shibboleth IdP, you would visit https://<IdPHOST>:8443/idp/shibboleth, copy the metadata content available there and paste it into the Hue metadata file.

Note:

You may have to edit the content copied over from your IdP's metadata file in case of missing fields such as port numbers (8443), from URLs that point to the IdP.

Step 3b: Private key and certificate files

To enable Hue to communicate with the IdP, you will need to specify the location of a private key, for the, key_file property, that can be used to sign requests sent to the IdP. You will also need to specify the location of the certificate file, for the cert_pem property, which you will use to verify and decrypt messages from the IdP.

Note: The key and certificate files specified by the key_file and cert_file parameters must be .PEM files.

Step 3c: Configure Hue to use SAML Backend

To enable SAML to allow user logins and create users, update the backend configuration property in hue.ini to use the SAML authentication backend. You will find the backend property 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

Page generated September 3, 2015.