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 slightly 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 and may interact with connecting to Secure Hadoop clusters.

Keytab mode

The recommended way to setup SPNEGO authentication is to get a keytab for the DSS service. This keytab allows DSS to authenticate to the KDC.

The keytab will be provided by your Kerberos administrator, together with the service principal (generally in the HTTP/dss_host@YOUR.REALM form)

You also need a krb5.conf file. Both the keytab and krb5.conf file must be installed on the DSS machine

Custom JAAS mode

For advanced use cases not covered by the previous modes

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

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