Cloudera Enterprise 5.15.x | Other versions

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

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 hue_sec_saml_auth.html#concept_dy1_1ps_m1b_unique_2__idp_metadata_unique_2), 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.
  Important: Read the documentation of your Identity Provider for details on how to procure the XML of the SAML server metadata.

Configure Hue at the Command Line

  Important: You may need to disable cipher algorithms. See SAML SSL Error in Troubleshooting below.
  1. 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
  2. Install xmlsec1 and xmlsec1-openssl on all hosts in the cluster:
      Important: Ensure that the xmlsec1 package is executable by the user, hue.
    ## 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
  3. 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
  4. 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.
  1. Log on to Cloudera Manager and go to Hue > Configuration.
  2. 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
      Note: For SLES distributions, the xmlsec binary may be in /usr/local/bin/. If so:
    • Set Hue Service Advanced Configuration Snippet: xmlsec_binary=/usr/local/bin/xmlsec1
    • Set Hue Service Environment Advanced Configuration Snippet: LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/
  3. 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.

  1. Ensure Hue is configured, restarted, and running.
  2. Go to http://<hue_fqdn>:8889/saml2/metadata.
  3. Copy the metadata and send it to your Identity Provider.
  4. 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 1. 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

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

Page generated May 18, 2018.