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.

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)

Mapping assertion attributes

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

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

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.

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