SAML properties

These SAML properties can be set in the hue.ini file for unmanaged clusters. A subset of them can be set in the Hue Service Advanced Configuration Snippet (Safety Valve) for hue_safety_valve.ini for managed clusters.

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.
want_response_signed A boolean parameter, when set to True, requires SAML response wrapper returned by an IdP to be digitally signed by the IdP. The default value is False.
want_assertions_signed A boolean parameter, when set to True, requires SAML assertions returned by an IdP to be digitally signed by the IdP. The default value is False.
xmlsec_binary Path to xmlsec_binary that signs, verifies, encrypts/decrypts SAML requests and assertions. Must be executable by user, hue.

SAML properties that can be set for managed clusters

  • 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>\/.$ 
  • backend [desktop]>[[auth]]
    Point to the SAML backend that is packaged with Hue:
    backend=libsaml.backend.SAML2Backend
  • xmlsec_binary [libsaml]
    Point to the xmlsec1 library path:
    xmlsec_binary=/usr/bin/xmlsec1
  • metadata_file [libsaml]
    Point to the path of the XML file you created from the identity provider'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 the hue.ini file. 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.