SAML properties

You can set SAML properties 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>\/.$ 
```
note
Hue uses redirect_whitelist to protect itself from redirecting to unapproved URLs.
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
```
note
To find the path, run: which 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.