Integrating with SSO¶
Available in 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:

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.
- wheremy-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 toIntegrate 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. SelectSAML
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, setReply URL
to<your_sso_gw_url>/result
, ie,https://my-sso-gateway.my-org.my-domain/result
, and save the settingsThis completes the configuration. You will need to:
download
Federation Metadata XML
file from theSAML Signing Certificate
sectiongrab the
Login URL
from theSet 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 Nucleus 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.