Integrating with SSO¶
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 it’s 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 (Azure AD, for example, requires the “bounce-back” redirect URL to be
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,
my-intranet.my-domainis 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 it’s own
.env) files. As with the base stack,
.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 certificate, and proper DNS hostname for the host running your
Also, note that while SSO Gateway has to be SSL, 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
Make sure you see a welcome page, and that SSL 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
Applicationor similarly named entity)
Applicationwith your SSO Gateway URL as the “bounce-back” URL - use
Determine and write down the IDP-provided login URL
Download the SAML Metadata XML
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
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
Set up single sign onsection. Select
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
https://my-sso-gateway.my-org.my-domain/result, and save the settings
This completes the configuration. You will need to:
Federation Metadata XMLfile from the
SAML Signing Certificatesection
Login URLfrom 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
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.