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 DSS user accounts for 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

When configured for SAML single-sign-on, DSS acts as a SAML Service Provider (SP), which delegates user authentication to a SAML Identity Provider (IdP).

To set up SAML integration, you need:

  • to register a new service provider entry on your SAML identity provider, for this DSS instance. This entry is identified by a unique “entity ID”, and is bound to the SAML login URL for this DSS instance.
  • to configure DSS with the IdP parameters, so that DSS can redirect non logged-in users to the IdP for authentication, and can authentify the IdP response
  • optionally, to configure which of the user attributes returned by the IdP is to be used as the DSS username, or configure rewrite rules to extract the DSS username from the chosen IdP attribute

These steps are individually detailed below.

Compatibility

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

  • OKTA
  • PingFederate PingIdentity (see note below)
  • Azure Active Directory
  • Google G.Suite
  • Microsoft Active Directory Federation Service (tested against Windows 2012 R2)
  • Auth0

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.

For AD FS, it is mandatory to configure at least one claim mapping rule which maps to “Name ID”, even if another attribute is used as the DSS login attribute.

Registering a service provider entry for DSS on the identity provider.

The exact steps for this depend on the identity provider platform which you plan to connect to, and should be performed by your IdP administrator. This entry may also be called a “SAML application”.

You will typically need:

  • an “Entity ID” which uniquely represents this DSS instance on the IdP (sometimes also called “Application ID URI”).

    This entity ID is allocated by the IdP, or chosen by the IdP admin.

  • the SAML login URL for DSS (“Assertion Consumer Service Endpoint”, which may also be called “Redirect URI”, “Callback URL”, or “ACS URL”).

    This URL must be configured as DSS_BASE_URL/dip/api/saml-callback, where DSS_BASE_URL is the URL through which DSS users access this DSS instance.

    For example, if DSS is accessed at https://dss.mycompany.corp/, the SAML callback URL must be defined as https://dss.mycompany.corp/dip/api/saml-callback.

    Note that some SAML identity providers require the callback URL to use the HTTPS scheme.

As an additional step, you may also have to authorize your users to access this new SAML application at the IdP level.

Finally, you will need to retrieve the “IdP Metadata” XML document from the identity provider, which is required to configure DSS (also called “Federation metadata document”).

Configuring DSS for SAML authentication.

SAML configuration is in the “Settings / Login (LDAP, SSO) & Security / SSO” screen.

Select “Enable”, choose protocol “SAML” and fill up the associated configuration fields:

  • IdP Metadata XML : the XML document describing the IdP connection parameters, which you should have retrieved from the IdP.

    It should contain a <EntityDescriptor> record itself containing a <IDPSSODescriptor> record.

  • SP entity ID : the entity ID (or application ID) which you have configured on the IdP in the step above

  • SP ACS URL : the redirect URL (or callback URL) which you have configured on the IdP in the step above

Warning

You need to restart DSS after any modification to the SAML configuration parameters.

Optional: configuring signed requests

If your IdP requires it (this is generally not the case) you can configure DSS to digitally sign SAML requests so that the IdP can authentify them.

For this, you need to provide a file containing a RSA or DSA keypair (private key plus associated certificate), which DSS will use for signing, and provide the associated certificate to the IdP so that it can verify the signatures.

This file must be in the standard PKCS#12 format, and installed on the DSS host. It can be generated using standard tools, as follows:

# Generate a PKCS12 file containing a self-signed RSA key and certificate with the "keytool" java command:
keytool -keystore <FILENAME>.p12 -storetype pkcs12 -storepass <PASSWORD> -genkeypair -keyalg RSA -dname "CN=DSS" -validity 3650

# Generate a PKCS12 file containing a self-signed RSA key and certificate with the openssl suite:
openssl req -x509 -newkey rsa:2048 -nodes -keyout <FILENAME>.key -subj "/CN=DSS" -days 3650 -out <FILENAME>.crt
openssl pkcs12 -export -out <FILENAME>.p12 -in <FILENAME>.crt -inkey <FILENAME>.key -passout pass:<PASSWORD>

You then need to complete the DSS configuration as follows:

  • check the “Sign requests” box
  • Keystore file : absolute path to the PKCS#12 file generated above
  • Keystore password : PKCS#12 file password
  • Key alias in keystore : optional name of the key to use, in case the PKCS#12 file contains multiple entries

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.

If this field is left empty, DSS will use the default SAML “name ID” attribute.

Login remapping rules

Optionally, you can define one or several rewriting rules to transform the selected SAML 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).

Testing SAML SSO

  • Configure SAML integration as described above
  • Restart DSS
  • Access the DSS URL from another browser or an anonymous window
  • You should be redirected to the Idp for authentication, then back to the DSS redirect URL, then to the DSS homepage
  • 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.

If the SAML configuration is invalid (in particular if the IdP metadata XML is malformed) DSS will not restart. You will need to manually disable SAML in the general-settings.json configuration file as described below.

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 declared in the DSS SP configuration does not match the expected EntityID / audience at the IdP level.

Response is destined for a different endpoint

Check the “ACS URL” in the DSS SP configuration. 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 a “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 IdP Metadata field), 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.

Login fails with “Unknown user <SOME_STRING>”

This typically means that SAML authentication of the user was successful at the IdP level, but that the returned attribute does not match any username in the DSS database (or in the associated LDAP directory if one has been configured).

It might be because you did not select the correct SAML attribute name in the DSS SAML configuration. You can check the list of attributes returned by the IdP in the DSS backend log file.

It might be because the attribute rewrite rule(s) did not lead to the expected result. This can also be checked in the DSS backend log file.

It might be because no DSS user exists with this name. You can create one in the DSS “Security / Users” page, using type “Local (no auth, for SSO only)”.

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.