Authenticate Hue Users with SAML

Hue supports 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, the Service Provider (Hue) sends an authentication request from the User Agent (browser) to the Identity Provider. The Identity Provider authenticates the user, sends a response, and redirects the browser back to Hue (see graphic).

This page explains how to configure Hue, the Service Provider, and gives guidance on how to configure the Identity Provider, which differs per product.

Configure Hue for SAML Authentication

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.

Continue reading:

Install and Configure IdP SAML Server
Configure Hue at the Command Line
Configure Hue in Cloudera Manager
Integrate IdP SAML Server with Hue

Install and Configure IdP SAML Server

The instructions on this page assume that you have an Identity Provider set up and running. You can use any Identity Provider–Okta, Ping, OpenAM, and so on.

In Configure Hue at the Command Line (step 3), you must copy the metadata from your IdP's SAML server and store it in an XML file on every ost with a Hue server.

Configure Hue at the 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 on every host with a Hue server.
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 self-signed certificate:
```
openssl req -x509 -newkey rsa:2048 -sha256 -days 3560 -nodes -keyout host.key -out host.pem -subj '/CN=Hue SAML' 
```

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 SAML configuration for Hue.
[desktop]
redirect_whitelist="^\/.*$,^https:\/\/idp.example.com:8080\/.*$"
[[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/host.key
cert_file=/opt/cloudera/security/saml/host.pem
username_source=nameid
name_id_format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
entity_id=[***HOST-BASE-NAME***]
logout_enabled=false

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

Integrate IdP SAML Server with 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 (IdP), you need a private key and certificate. The private key signs requests sent to the IdP, and decrypts messages from the IdP. The certificate is used to encrypt messages to Hue from the IdP, and must be provided to the IdP. Typically, the cert_file is shared by providing Hue's Service Provider metadata XML to the IdP admins, but you may also share a copy of the cert_file itself.

The SAML certificate and private key must be the same on all Hue Server hosts, and can be self-signed, obtained from a commercial CA vendor, or from your internal PKI administrators. Both key_file and cert_file must be in PEM format.

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

Remember to Enable DEBUG for logging.

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 with LDAP Server

Authorize Groups with Sentry