Single Sign-On

DSS can be configured to perform single-sign-on, so that your users don’t have to type their password when accessing DSS.

DSS supports the following SSO protocols:

  • SAML v2
  • SPNEGO / Kerberos

Warning

We strongly advise using SAML SSO rather than SPNEGO / Kerberos. Setting up SPNEGO is fairly difficult and may interact with connecting to Secure Hadoop clusters.

Users database

In SSO mode, users don’t need to enter their password. Instead, the SSO system provides the proof that the person performing the query is who she pretends to be, and DSS verifies this proof.

However, DSS must still know “who” the user is, and importantly, to which groups it belongs, in order to enforce security.

Thus, in SSO mode, DSS still needs to have a database of all users who may log in, even if they don’t enter a password. This database can either be:

Using local users

If you don’t have or don’t want to install LDAP, you need to create users corresponding to the SSO users. When creating these users, select “Local (no auth)” as source type. This way, only a login and display name are required, you don’t need to enter a password (since users won’t enter passwords, in SSO mode)

SAML

DSS acts as a SAML Service Provider (SP), which can authenticate to an Identity Provider (IdP).

To configure SAML login, you need:

  • The SAML IdP metadata file (it’s an XML file)
  • The SAML SP metadata file (it’s an XML file)

The DSS SAML callback URL is DSS_BASE_URL/dip/api/saml-callback. For example if DSS is accessed at https://dss.mycompany.corp/, the SAML callback URL is https://dss.mycompany.corp/dip/api/saml-callback. You will generally need to declare this URI to your IdP.

Compatibility

DSS has been successfully tested against the following SAML identity providers:

  • OKTA
  • PingFederate PingIdentity (see note below)
  • Azure Active Directory
  • Google G.Suite (requires DSS 4.1.6 or later)

Note

For PingIdentity, it is mandatory to uncheck the Always sign the SAML assertion property when configuring the DSS service entry on the identity provider interface.

Generating the SP metadata

The IdP metadata file is generally provided by your SAML administrator.

The SP metadata file can generally be generated. Online tools like https://www.samltool.com/sp_metadata.php can help you for this.

You will need at least to enter:

  • The EntityId is the “name” that DSS uses to talk to the IdP. This name must generally be declared to the IdP, as the “audience”.
  • The “Attribute Consume Service Endpoint” is the DSS SAML callback URL (see above)

Choosing the login attribute

Upon successful authentication at the IdP level, the IdP sends to DSS an assertion, which contains all attributes of the logged in user. Each attribute is named. You need to indicate which of the attributes contains the user’s login, that DSS will use.

Note that DSS logs all attributes received from the SAML server in the backend log file (DSS_DATADIR/run/backend.log), which may help configuring this field.

Login remapping rules

Optionally, you can define one or several rewriting rules to transform the selected attribute into the intended DSS username. These rules are standard search-and-replace Java regular expressions, where (...) can be used to capture a substring in the input, and $1, $2… mark the place where to insert these captured substrings in the output. Rules are evaluated in order, each one working on the output of the previous one.

A standard use case for such rewriting rules would be to strip the domain part from email-address-like attributes. For example, configuring the following rule:

([^@]*)@mydomain.com     ->     $1

would rewrite a SAML attribute first.last@mydomain.com into first.last, and do nothing on SAML attribute first.last@otherdomain.com (as the left-hand part of the rule would not match).

Configuring SAML SSO

  • Go to Administration > Settings > LDAP & SSO
  • Enable the SSO checkbox, select SAML, and enter the text of the IdP metadata and SP metadata files
  • Enter the attribute name
  • Restart DSS
  • Access the DSS URL
  • If login fails, check the logs for more information

Note

Once SSO has been enabled, if you access the root DSS URL, SSO login will be attempted. If SSO login fails, you will only see an error.

You can still use the regular login/password login by going to the /login/ URL on DSS. This allows you to still log in using a local account if SSO login is dysfunctional.

Troubleshooting

No details are printed in case of wrong SSO configuration. All details are only in the logs.

Common issues include:

Assertion audience does not include issuer

This means that the EntityID in the SP metadata XML file does not match the expected EntityID / audience at the IdP level

Response is destined for a different endpoint

Check the “AssertionConsumerService” in your SP metadata. It must match the response destination in the IdP answer, ie generally the callback declared in the IdP.

This error message also shows up when the IdP does not include the “Destination” attribute in the response message. This attribute is mandatory and should match the DSS SAML callback URL.

When using PingFederate PingIdentity as an IdP make sure to uncheck the Always Sign the SAML Assertion property when defining the DSS endpoint, to ensure that a Destination attribute is included in the Response message.

DSS would not start after configuring SAML SSO

In some cases (in particular, entering invalid XML in the entity descriptor fields), an incorrect SAML configuration may prevent the DSS backend to start. In such a case, open the DSS_DATADIR/config/general-settings.json configuration file with a text editor, locate the "enabled" field under "ssoSettings" and set it to false. You should then be able to restart and fix the configuration using the DSS interface.

SPNEGO / Kerberos

Warning

While this is somewhat related to Kerberos securization of secure Hadoop clusters, these are two very different and independent features

Warning

We strongly advise using SAML SSO rather than SPNEGO / Kerberos. Setting up SPNEGO is fairly difficult, requires specific configuration of the user browsers, and may interact with connecting to Secure Hadoop clusters.

Keytab mode

The recommended way to setup SPNEGO authentication is to create a service principal for DSS in your Kerberos database, along with an associated keytab file. This keytab allows DSS to authenticate the users identity through the Kerberos login session of their browser.

The principal and keytab will be provided by your Kerberos administrator. The keytab file must be installed on the DSS machine, in a filesystem location readable by, and private to, the DSS Unix service account.

You may also have to provide a krb5.conf file if the server does not have a suitable one in the default system location. This file will also be provided by your Kerberos administrator.

Note

The Kerberos principal used by DSS for SPNEGO authentication MUST be of the form HTTP/<dss_hostname>@<realm> where <dss_hostname> is the hostname of the DSS service URL as seen from the client’s browser.

On Windows Active Directory, service principals are created by:

  • creating a user account for DSS in the domain
  • associating the required service principal to this account, using the command-line ‘setspn’ tool (you can also do it using extra arguments to the ‘ktpass’ command which issues the Kerberos keytab file).

Custom JAAS mode

For advanced use cases not covered by the previous mode. Requires advanced knowledge of Kerberos configuration for Java.

Login remapping rules

Optionally, you can define one or several rewriting rules to transform the user identity provided by SPNEGO (which is the Kerberos principal of the user, typically username@REALM) into the intended DSS username.

These rules are standard search-and-replace Java regular expressions, where (...) can be used to capture a substring in the input, and $1, $2… mark the place where to insert these captured substrings in the output. Rules are evaluated in order, each one working on the output of the previous one.

For convenience, a standard rule which strips the @REALM part of the user principal can be enabled by a checkbox in the configuration. This rule is evaluated first, before any regular expression rules.

Configuring SPNEGO SSO

  • Go to Administration > Settings > LDAP & SSO
  • Enable the SSO checkbox, select SPNEGO, and enter the required information
  • Restart DSS
  • Access the DSS URL
  • If login fails, check the logs for more information

Note

Once SSO has been enabled, if you access the root DSS URL, SSO login will be attempted. If SSO login fails, you will only see an error.

You can still use the regular login/password login by going to the /login/ URL on DSS. This allows you to log in if SSO login is dysfunctional

Note

You will typically need to perform additional configuration on the user browsers so that they attempt SPNEGO authentication with DSS. This usually includes:

  • making sure the user session is logged on the Kerberos realm (or Windows domain) before launching the browser
  • adding the DSS URL to the list of URLs with which the browser is authorized to authenticate using Kerberos

Refer to your browser documentation and your domain administrator for the configuration procedures suitable for your site.

Troubleshooting

No details are printed in case of wrong SSO configuration. All details are only in the logs.

SPNEGO failures are notoriously hard to debug because all communication is encrypted, and any error simply leads to decryption failures.

Usual things to double-check:

  • The mapping of domain_realm in your krb5.conf
  • The principal in the keytab must match the one declared in DSS
  • The principal in the keytab must be HTTP/<dss_hostname>@<realm> where <dss_hostname> matches the DSS URL hostname.
  • The browser must be configured to allow SPNEGO authentication on <dss_hostname>. In particular, error messages mentioning NTLM authentication failures actually mean that this configuration is not working as expected.