Authenticate Hue with SAML

Hue supports SAML (Security Assertion Markup Language) for Single Sign-on (SSO) authentication. You can use any Identity Provider (such as Shibboleth, Okta, Ping, OpenAM) .

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.

Configure Hue for SAML

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.

Prerequisites

The instructions on this page assume that you have an Identity Provider set up and running. See SSO with Hue: new SAML backend for a demo on configuring Shibboleth as the Identity Provider.

Configure Hue at Command Line

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

Install xmlsec1 and xmlsec1-openssl on all hosts in the cluster:

## RHEL/CentOS 
yum install xmlsec1 xmlsec1-openssl

Note: If xmlsec libraries are not available, use the appropriate epel repository:

## For RHEL/CentOS 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

## Ubuntu/Debian
apt-get install xmlsec1 libxmlsec1-openssl

## SLES (get latest version)
wget http://www.aleksey.com/xmlsec/download/xmlsec1-1.2.24.tar.gz
tar -xvzf xmlsec1-1.2.24.tar.gz
cd xmlsec1-1.2.24
./configure && make
make install

Copy metadata from your IdP's SAML server and save it as an XML file.
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.
Note: You may have to edit the copied metadata; for example, the IdP's port number (8443) may be missing from its URL.
```
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
```
Add key_file and cert_file for encrypted assertions–see Table of SAML Parameters.
Warning: Add key and cert files even if not encrypting assertions. Hue checks for the existence and validity of these files even if they are not needed! They cannot be empty files. This is a known issue.
If necessary, create "valid" dummy files:
```
openssl genrsa -des3 -out dummy.key 2048
openssl rsa -inform PEM -outform PEM -in dummy.key -pubout -out dummy-nopass.pem
```

Configure Hue in Cloudera Manager

Currently, all hue.ini properties for SAML must be added to Hue Service safety-valve in Cloudera Manager.

Log on to Cloudera Manager and go to Hue > Configuration.

Configure Hue Service Advanced Configuration Snippet (Safety Valve) for hue_safety_valve.ini with:

## Example Settings using Open AM:
[desktop]
redirect_whitelist="^\/.*$,^http:\/\/clr.sec.cloudera.com:8080\/.*$"
[[auth]]
backend=libsaml.backend.SAML2Backend
[libsaml]
xmlsec_binary=/usr/bin/xmlsec1
metadata_file=/opt/cloudera/security/saml/idp-openam-metadata.xml
key_file=/opt/cloudera/security/saml/host.key
cert_file=/opt/cloudera/security/saml/host.pem
username_source=nameid
name_id_format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
entity_id=<host base name>
logout_enabled=false

Click Save Changes, then select, Actions > Restart Hue.

Configure SAML for 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.

Ensure Hue is configured, restarted, and running.
Go to http://<hue_fqdn>:8889/saml2/metadata.
Copy the metadata and send it to your Identity Provider.
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.
```
[desktop]
redirect_whitelist=^\/.$,^https:\/\/<SAML_server_fully_qualified_domain_name>\/.$ 
```
Note: Hue uses redirect_whitelist to protect itself from redirecting to unapproved URLs.
backend [desktop]>[[auth]]
Point to the SAML backend (packaged with Hue):
```
backend=libsaml.backend.SAML2Backend
```
xmlsec_binary [libsaml]
Point to the xmlsec1 library path:
```
xmlsec_binary=/usr/bin/xmlsec1
```
Note: To find the path, run: which xmlsec1
metadata_file [libsaml]
Point to the path of the XML file you created from the IdP's metadata:
```
metadata_file=/path/to/<your_idp_metadata_file>.xml
```
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.

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

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.

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:

Download and rename Python script, fix-xmlsec1.txt.

wget http://www.cloudera.com/documentation/other/shared/fix-xmlsec1.txt -O fix-xmlsec1.py

Change permissions as appropriate, for example:
```
chmod 755 fix-xmlsec1.py
```
In hue.ini, set xmlsec_binary=<path_to_script>/fix-xmlsec1.py.
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.

Categories: Authentication | Hue | SAML | Security | All Categories

Synchronize Hue with LDAP

Hue How-tos