Integrating with SSO

Nucleus 2021.2.0

Currently, Nucleus supports integration with SAML Identity Providers (IDPs). We have extensively tested Azure AD SAML, but in theory other SAML IDPs should work as well.

Before proceeding with SSO integration, it would be useful to understand the basic principles of how SSO authentication works with Nucleus, so we shall begin with that.

We highly recommend reading thru the document in its entirety prior to an attempted setup.

How it Works

Three parties are involved in SSO: SAML-based Identity Provider, Nucleus itself as a consumer, and Nucleus SSO Gateway as a helper service. Latter two are Omniverse entities, and beg description.

  • Nucleus itself needs an identity - an account - for a client’s connection. Note that Nucleus Core does not really care where the account is coming from - it uses its own internally generated JSON Web tokens (JWT) to authenticate a user. Nucleus includes an Authentication Service specifically to introduce this abstraction. The Authentication Service can take a specific auth method, and, once a user is authenticated with that method, issue a JWT internal to Nucleus. Note that in case of authentication with passwords, Auth Service acts as an identity provider in addition to issuing JWT , whereas with SSO it acts as an intermediary, bouncing a user to a third-party IDP and then, basically, parsing the IDP’s return.

  • Nucleus SSO Gateway is seemingly unnecessarily complicating things, however, it makes it convenient to integrate with IDPs like Azure AD, which insist on redirecting a user to a particular URL themselves once authentication is completed. SSO Gateway acts as a “sink” for these redirects, being aware of their payloads, and is able to redirect a user to a desired Nucleus instance. This is extremely convenient when one runs many instances of Nucleus (this way integration with Azure can be done once rather than once per instance), or when Nucleus instance(s) themselves aren’t configured with SSL/TLS (Azure AD, for example, requires the “bounce-back” redirect URL to be https://...).

The following diagram shows basic interactions:

../../../_images/prod_nucleus_sso_arch.png

Note that SSO Authentication is web browser based - even in various Omniverse Apps and Connectors - so here, effectively, Client is a Browser.

  • When Client elects the SSO Authentication option (line 1), she gets sent to a pre-configured SAML IDP URL (this URL is supplied by the IDP system, and should be configured within Nucleus’s Auth Service) (line 2).

  • She then interacts with the SAML IDP and authenticates (line 3).

  • Upon successful authentication, the IDP sends the Client over to Nucleus SSO Gateway, the URL of which is configured on the IDP side. Note that the hostname of that URL has to be resolvable by the Client - so it can be a hostname that’s meaningful only on an intranet (ie, nucleus-sso-gateway.my-intranet.my-domain. - where my-intranet.my-domain is not a valid DNS name on the Internet). Line 4.

  • SSO gateway examines the payload returned by the IDP, and determines which (of possibly many) Nucleus instances this authentication attempt was for. It then sends the Client back to Nucleus (line 5), which,…

  • …after validating SAML response, issues an appropriate internal JWT for this connection, and the session proceeds using this JWT.

Configuring SAML Integration

Given the above description of fundamentals, there are three major steps in the SAML integration process:

  • Deploying Nucleus SSO Gateway

  • Configuring your SAMP IDP

  • Configuring your Base Stack

Deploying the SSO Gateway

SSO Gateway ships as a part of your install artifact. It consists of its own docker-compose and settings (.env) files. As with the base stack, review the .env file and configure appropriate things as required.

Note that at least Azure AD requires the “bounce-back” URL (Reply URL) - which SSO Gateway is providing - to be HTTPS. This means that you will need an SSL/TLS certificate, and proper DNS hostname for the host running your SSO Gateway.

Also, note that while SSO Gateway has to be SSL/TLS, Nucleus does not - in other words, it is possible to have a non-SSL Nucleus using SAML SSO.

Once the Gateway is up, try to access the URL of the SSO Gateway with your browser, ie, point the latter to https://my-sso-gateway.my-org.my-domain[:port]/. Make sure you see a welcome page, and that SSL/TLS cert validation worked properly.

Configuring SAML IDP

In general, on the SAML IDP’s side, you will need to:

  • Create an “entity” representing your Nucleus deployments (an Application or similarly named entity)

  • Configure your Application with your SSO Gateway URL as the “bounce-back” URL - use <your_sso_gw_url>/result, ie, https://my-sso-gateway.my-org.my-domain/result

  • Determine and write down the IDP-provided login URL

  • Download the SAML Metadata XML

    • Please note that the Metadata XML must be using RSA-SHA256 XML signatures

Configuring Azure AD

Below is a quick summary of steps for configuring Azure AD SAML IDP. Azure AD Setup: Screenshots provides the setup process in screenshots.

  • Go to your Azure AD and log in to an appropriate org with admin privileges

  • Find Enterprise applications (best way to do it is to use the search bar)

  • Add a new application. Nucleus is not in the Gallery, so you have to select Create your own application, name it with something appropriate, and elect to Integrate any other application you don't find in the gallery (Non-gallery).

  • Assign users and / or groups to the newly created Application

  • Go to Set up single sign on section. Select SAML

  • In Basic SAML Configuration, configure Identifier to be your SSO Gateway URL (ie, https://my-sso-gateway.my-org.my-domain, we’re assuming it’s on port 443 here) and make sure to delete the default one. Next, set Reply URL to <your_sso_gw_url>/result, ie, https://my-sso-gateway.my-org.my-domain/result, and save the settings

  • This completes the configuration. You will need to:

    • download Federation Metadata XML file from the SAML Signing Certificate section

    • grab the Login URL from the Set up <your app name here> section

Configuring your Base Stack

Now, let’s put everything together.

Last step is to configure your Base Stack to support SSO. If it wasn’t deployed yet, we recommend deploying it without SSO first - to confirm that the stack works - and then adding SSO on top. As customary, specific SSO related options and their descriptions are located in the Base Stack’s .env file. You will need to configure the URL of your SSO Gateway, Login URL, and provide the Metadata XML.

Once configured, restart the stack, open up the Omniverse Navigator (server’s Web UI) in the browser, and attempt to log in with an SSO user. You should go thru a series of redirects, and be bounced back to the Navigator, now logged in with your SAML IDP account.