SAML Authentication Plug-in

Overview

Security Assertion Markup Language (SAML) can be used for external authentication of users for both the Deephaven Web interface and the Deephaven Classic (Java/Swing) interface.

SAML is an open standard whereby third-party Identity Providers such as Google, Okta, OneLogin, and others, can validate the identity of a user requesting to log on to a Deephaven system. The main benefits of SAML authentication are single sign-on to multiple services, including Deephaven, and the possibility to manage various forms of two-factor authentication.

There are two systems involved in authentication using SAML: the Identity Provider and the Service Provider. The Identity Provider is responsible for authenticating a user and providing evidence of that user's identity in the form of a SAML assertion. Google, Okta, and other accounts management solutions that support SAML 2.0 can act as Identity Providers for Deephaven. The other side of the configuration is the Service Provider, which makes services available to authenticated users. In the context of this document, the Service Provider is the Deephaven installation, with the Service Provider endpoint being a component of the Deephaven authentication server.

Both systems need to be configured for SAML authentication: the Identity Provider so it will accept authentication requests and return responses in the expected format from the specific Service Provider installation, and the Service Provider so it will know what Identity Provider instance to work with and will trust assertions received from it.

Once both systems are properly configured, users attempting to log in to Deephaven can choose to authenticate with the external Identity Provider. If they do so, they will be redirected to a login process managed by the Identity Provider. Upon completion of that process, the result will be sent as a SAML-formatted assertion message to the Deephaven authentication server. If the login was successful, the authentication server will grant the user the rights associated with the user name indicated in the assertion.

For a user to access Deephaven with SAML authentication, the Identity Provider administrator must create a login in the Identity Provider system and then grant the user access to the Deephaven application there. In addition, a Deephaven administrator must create a Deephaven login to match the user's Identity Provider login name, and grant the user's Deephaven account any needed privileges with the Deephaven system.

Configuring Deephaven to Use SAML Authentication

The extensions to the authentication process are implemented as a Deephaven plug-in. This plug-in is installed from an RPM using yum, which will place its components into /etc/sysconfig/illumon.d/plugins:

sudo yum localinstall ./SamlAuth-<versionnumber>.x86_64.rpm

After this step, activate the plug-in:

sudo /etc/sysconfig/deephaven/plugins/samlAuth/bin/activate.sh --classpath

To configure the authentication server to present the option of SAML authentication, two sets of properties need to be added to the iris-environment properties file: one for front-end configuration and one for server-level configuration.

The front-end configuration is defined within the stanza:

service.name=iris_console|interactive_console|web_api_service

These properties are used to enable the SAML login option within the Deephaven console and web UI:

  • authentication.server.list=<list of infra-hosts>: This must be set, with at least one of the specified addresses being a server that accepts the SAML HTTPS request and is prepared to accept connections on the specified domain socket
  • authentication.client.customlogin.class.SAMLAuth=com.illumon.iris.console.utils.WAuthenticationSAMLLoginMethodPanel
  • authentication.client.custlogin.priority.SAMLAuth=1
  • authentication.client.samlauth.login.url=<URL on which the SAML auth client will listen for authentication assertions from the Identity Provider>:9032/dh-saml/ - This is the internal URL (which the Deephaven login screen links to) that redirects to the Identity Provider.
  • authentication.client.saml auth.provider.name=<your_provider; e.g.,Okta> - This is the name shown on the Deephaven login screen (e.g., Okta, Google, or your chosen external Identity Provider).
  • authentication.client.configuration.list=<authentication.client.samlauth.provider.name,authentication.client.samlauth.login.url,authentication.client.customlogin.class.SAMLAuth,authentication.samlauth.idp.single_sign_on_service.url>
  • authentication.samlauth.idp.single_sign_on_service.url=<URL provided by the Identity Provider where SSO requests should be sent>

The second set is to enable the authentication server to accept and handle SAML-based authentication requests. This set of properties should be added to the authentication server stanza:

service.name=authentication_server:

These properties are:

  • authentication.server.customauth.class.SAMLAuth=io.deephaven.samlauth.SAMLAuthModule - Must be set to the full name of the plug-in.
  • authentication.server.customauth.priority.SAMLAuth=1 - If there are multiple authentication mechanisms, such as SAML and SSH, this property defines which is listed first, second, and so on.
  • #authentication.samlauth.sp.entityid = <deephaven:iris:saml:sp> - The default value is deephaven:iris:saml:sp; however, this exact value must match between the Service Provider (the Deephaven configuration) and the Identity Provider (SAML).
  • authentication.samlauth.jetty.redirect.list = <URL of the Deephaven Web IDE system>:8123/iriside/ - This property defines a whitelist of URLs to which client front-end applications may request redirection. The auth-server will verify that the user-requested URL is permitted before redirecting.
  • authentication.samlauth.sp.assertion_consumer_service.url = <URL of the Deephaven authentication server system>:9032/dh-saml/acs
  • authentication.samlauth.idp.entityid = <e.g., http://www.okta.com/exk16niksqHbbxXaT4x6>
  • authentication.samlauth.idp.single_sign_on_service.url = <e.g., https://dev-349029.okta.com/app/deephavendatalabsdev349029_deephaven_1/exk16niksqHbbxXaT4x6/sso/saml>
  • authentication.samlauth.idp.x509cert.file = </etc/sysconfig/illumon.d/auth/okta-saml.cert> - This property should point to the file location of the certificate.
  • authentication.samlauth.contacts.support.given_name = <Contact name to display in case of SSO authentication failure>
  • authentication.samlauth.contacts.support.email_address = <Contact email to display in case of SSO authentication failure>
  • authentication.samlauth.tokenTimeoutMillis=<60000> - An optional property, defaulting to 60s, determining how many milliseconds may pass before a SAML IdP token is timed-out in the case that no usable timeout is received from the Identity Provider.

When SAML is configured, the Deephaven login screen will look similar to the following: