This article will cover how to configure your Hyperglance appliance for Single-Sign-On (SSO) authentication using SAML 2.0 foHyperglance v5.2+.


In this mode the Hyperglance appliance acts as a Service Provider (SP) and will delegate its authentication to an external Identity Provider (IdP). By default SAML is not enabled and the Hyperglance webapp is responsible for displaying its own login-screen and authenticates users against its internal database.


The Hyperglance web application is served from behind an Apache HTTPD 2.4 reverse-proxy (supplied within the Hyperglance appliance), this proxy comes pre-installed with a SAML module called mod_auth_mellon that we can enable and configure to activate SAML integration:


Setup Procedure

Step 1 - Configure the Hyperglance webapp for proxy authentication

This informs Hyperglance to not display a login-screen:

  • Edit config file: /opt/wildfly/standalone/deployments/hgs.ear/lib/common.jar/runtime.properties
  • Set the flag:  sso.enabled=true


Step 2 - Activate SAML on the reverse proxy

  • Edit: /etc/httpd/conf.d/ssl.conf
  • Uncomment by removing the hash character on this line:
    • #Include conf/saml.conf


Step 3 - Generate Service Provider (SP) metadata

  • Goto folder: cd /etc/httpd/mellon
  • Run metadata creation script: ./mellon_create_metadata.sh {entity-id-uri} {saml-endpoint-url}
  • Running the script will have generated 3 files but they need to be renamed to sp.xml, sp.key and sp.cert:
    • mv *.xml sp.xml
      mv *.key sp.key
      mv *.cert sp.cert
  • That script will also print out the SSO URL (https://{ip-address-of-your-hyperglance}/saml/postResponse


Step 4 - Configure Your Identity Provider 

  • You will need to configure your IdP with the information you entered and retrieved from step 3.
    Here are some tips:
    • Some IdP's allow you to upload the sp.xml metadata file to simplify setup.
    • Some IdP's (e.g. Okta) ask for the SSO URL (the one ending in /postResponse) while some (e.g. KeyCloak) only ask for the endpoint URL (the one ending in /saml).
    • Some IdP's (e.g. Okta) refer to the the entity-id-uri as the "Audience Restriction".


Required SAML Attributes

  • Hyperglance requires 2 SAML attributes: NAME_ID and Role.
  • NAME_ID is a standard SAML attribute that your IdP will pass to Hyperglance. Your IdP will probably let you to choose 'what' is used as the NAME_ID (email, first-name, username, etc).
  • Role is a custom attribute statement that you will need to add. You can either:
    • a) Add a single Role attribute that is a semi-colon-separated list of Hyperglance roles.
    • b) Add multiple Role attributes, one per Hyperglance role. (Not all IdP's support this, e.g. Okta does not)


Example Setup Using Okta:


Below is a screenshot (from Okta) of a working SAML setup.

Since Okta does not support multiple SAML attributes with the same name so we pass a single Role attribute with a semi-colon-separated list of Hyperglance roles.

On this occasion, for simplicity, we used the same URL for both arguments to the shell script:



Step 5 - Add Identity Provider (IdP) metadata



Step 6 - Restart services

  • sudo service wildfly restart
  • sudo apachectl restart



Testing it Out

  1. Using Incognito/InPrivate mode visit your Hyperglance appliance in a web browser: https://{ip-address}
  2. You should be redirected to the IdP login screen.
  3. Login via your IdP
  4. You should now be redirected back to Hyperglance's topology screen.


Did it work?

If yes - Great! You're done.

If not - Proceed to the troubleshooting section below.



Troubleshooting

Problems may be due to misconfiguration, either on the Hyperglance appliance (SP) or at the IdP.

Here are some helpful things to check that may help you track down an issue:

  • Re-trace these instructions carefully.
  • Manually inspect the sp.xml and the idp.xml files and ensure that all URLs,  IP addresses and ports are correct from the point-of-view of the user's browser (NOT necessarily from the point-of-view of the Hyperglance appliance box!)
  • Validate your apache config by running: apachectl configtest
  • Check the proxy logs: /etc/httpd/logs
    • You may also need to adjust the logging level to "debug" (or lower!) in /etc/httpd/conf/httpd.conf and/or /etc/httpd/conf.d/ssl.conf
    • Read more about httpd logging levels.
  • Check the logs on your IdP
  • Ensure that you have configured your IdP correctly against the sp.xml file and that it expects to redirect to the /saml endpoint.
    • It may help to (temporarily) disable any checks that your IdP does for signed responses.
  • See if your issue is documented by mod_auth_mellon:
  • Search for online any dedicated guides on how to configure your IdP with a mod_auth_mellon SP. Such instructions would be highly applicable to Hyperglance.



[Advanced] The 'mod_auth_mellon' Configuration

Note: You generally don't need to know this to setup SAML with Hyperglance unless you wish to make advanced changes to the configuration such as customizing the requisite SAML attributes or adjusting the endpoint URL.


Hyperglance ships with a ready-made configuration for mod_auth_mellon in: /etc/httpd/conf/saml.conf

This section describes some of the note-worthy aspects of this configuration:


1) The SAML endpoint path is set to: /saml

You do not need to change this but you do need to know it when generating the SAML metadata and configuring your IdP.


2) This file sets the headers that are passed from the HTTPD proxy to the internal Hyperglance webapp:

  • X-HG-USERNAME   -- Simply a name by which to know the user. This name is displayed in the product.
  • X-HG-ROLES      -- A semi-colon-separated list of roles and follows the same conventions as the roles.properties file discussed in the RBAC article.


These headers must be sent through on every request.

By default they are mapped from a couple of HTTPD env-vars named MELLON_NAME_ID and MELLON_Role respectively:

  • These env-vars relate to SAML attribute statements as described on the Github readme for mod_auth_mellon: SAML attributes are made available as HTTPD env-vars with a "MELLON_" prefix.
  • Therefore "MELLON_NAME_ID" and "MELLON_Role" env-vars refer to "NAME_ID" and "Role" SAML attributes.
  • You can change these if you wish to use different SAML attributes.
  • You must ensure that your IdP is producing corresponding SAML attribute statements (for example: If you use KeyCloak as your IdP it has 'mappers' for this purpose).
  • The configuration file uses the MellonMergeEnvVars property to collapse multiple role attributes into a single semi-colon separated value for MELLON_Role.