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


The Hyperglance web application is always served from behind an Apache HTTPD 2.4 reverse-proxy. This proxy is a standard part of the Hyperglance appliance.

  • By default this proxy does not perform any authentication and the Hyperglance webapp is responsible for displaying its own login-screen and authenticates users against its internal database.
  • But it is possible to offload the authentication responsibility to the reverse-proxy itself - In this mode the proxy performs the auth and passes users' details to the Hyperglance webapp as HTTP headers.


Using an authenticating proxy opens up possibilities for using Single-Sign-On (SAML, OpenID, etc) or other kinds of auth.

There are a variety of standard and 3rd party auth modules available for Apache HTTPD that could be used to achieve this.


The Hyperglance appliance comes pre-installed with a well-regarded httpd SAML module called mod_auth_mellon which we will use to configure SSO with SAML.


About 'mod_auth_mellon' configuration

The Hyperglance appliance ships with default configuration for mod_auth_mellon: /etc/httpd/conf/saml.conf


On the whole you can leave this file alone. However there are a couple of things to note:


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

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


2) This file sets the headers that are passed from the proxy to the 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 should 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.



Setup Procedure

Step 1 - Configure the Hyperglance webapp for proxy authentication

  • Edit config file: /opt/wildfly/standalone/deployments/hgs.ear/lib/common.jar/runtime.properties
  • Set the flag:  sso.enabled=true
    • This flag informs the application to not display a login-screen and to expect the user details to passed via HTTP headers.


Step 2 - Configure Grafana for proxy authentication

  • Edit config file: /etc/grafana/grafana.ini
  • Make the following changes:

[users]

allow_sign_up = false

auto_assign_org = true

auto_assign_org_role = Editor


[auth]

disable_signout_menu = true


[auth.proxy]

enabled = true

header_name = X-HG-USERNAME

header_property = username

auto_sign_up = true



Step 3 - Enable SAML config on reverse proxy (httpd)

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


Step 4 - 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. Rename them to match the filenames set in saml.conf:
    • mv *.xml sp.xml
      mv *.key sp.key
      mv *.cert sp.cert
  • You will need to configure your IdP with this same information. Your IdP may even allow you to upload the sp.xml metadata file to simplify setup.


Note: It may have also been possible to generate these files from within your IdP and download them to the Hyperglance appliance. Either way both the SP and IdP need to be configured with the same metadata.



Step 5 - Add Identity Provider (IdP) metadata



Step 6 - Restart services

  • sudo service wildfly restart
  • sudo service grafana-server 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.