.. _sso: =============== SSO Integration =============== Overview ======== An Enterprise Nucleus Server supports integration with SAML Identity Providers (IDPs). We currently support both :doc:`Microsoft Azure AD ` and `Okta `__, but other SAML IDPs should work as well that align to the standard. Before integrating with your SSO provider, we highly recommend that you review the information below that explains the basic principles of how SSO authentication works with Nucleus. How it Works ============ When integrating with SSO, there are three components involved: The SAML-based Identity Provider, Nucleus itself as a consumer, and the Nucleus SSO Gateway as a helper service. * Nucleus itself needs an identity - an account - for a client's connection. Note that Nucleus Core does not have a preference where the account is coming from - it uses its own internally generated `JSON Web tokens (JWT) `__ to authenticate a user. Nucleus includes an :ref:`Authentication Service` specifically to handle this abstraction. The Authentication Service can take a specific authentication method, and once a user is authenticated with that method, issue a JWT to Nucleus. In the case of authentication with passwords, the authentication service acts as an identity provider in addition to issuing JWT, whereas with SSO it acts as an intermediary, redirecting a user to a third-party IDP and then, parsing the return. * The Nucleus SSO Gateway makes it convenient to integrate with IDPs, which insist on redirecting a user to a particular URL *themselves* once authentication is completed. The SSO Gateway acts as a "endpoint" 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, or when Nucleus instance(s) themselves aren't :doc:`configured with SSL/TLS ` The following diagram explains the basic interaction: .. image:: sso/prod_nucleus_sso_arch.png :align: center Note that SSO Authentication is web browser based - even within various Omniverse Apps and Connectors - so each Client *is* effectively a browser. * When a Client elects the SSO Authentication option **(Reference 1)**, it's sent to a pre-configured SAML IDP URL. (This URL is supplied by the IDP provider, and must be configured within Nucleus's Authentication Service.) **(Reference 2)** * The Client then interacts with the SAML IDP and authenticates. **(Reference 3)** * Upon successful authentication, the IDP sends the Client to the 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 on an Intranet (i.e., :code:`nucleus-sso-gateway.my-intranet.my-domain` - where :code:`my-intranet.my-domain` is *not* a valid DNS name on the Internet.) **(Reference 4)** * The SSO gateway examines the payload returned by the IDP, and determines which (of possibly many) Nucleus instance this authentication attempt was for. It then sends the Client back to Nucleus **(Reference 5)**, which after validating the SAML response, issues an internal JWT for this connection and the session continues. Configuring SAML Integration ============================ Given the above description of fundamentals, there are three steps in the SAML integration process: * Deploying the Nucleus SSO Gateway * Configuring your preferred SAML IDP * Enabling and configuration the Nucleus Base Stack for SSO Deploying the SSO Gateway ------------------------- The SSO Gateway ships as a component of the Nucleus artifact. It consists of its own :code:`docker-compose` and settings (:code:`.env`) files. Akin to configuring the Nucleus base stack, review the :code:`.env` file and configure as needed. Most IDP's require the "bounce-back" URL (:code:`Reply URL`) to be :code:`HTTPS`. This means that you will need an SSL/TLS certificate, and proper DNS hostname for the host running your SSO Gateway. Also, while the SSO Gateway **must** to be SSL/TLS enabled, Nucleus does not. While not recommended, it is possible to have a non-SSL Nucleus using SAML SSO. Configuring SAML IDP -------------------- On the SAML IDP's side, you will need to: * Create an *entity* or *application* for your Nucleus deployment * Configure the *application* with your SSO Gateway URL as the "bounce-back" URL (i.e., :code:`https://my-sso-gateway.my-org.my-domain/result`) * Gather and obtain the IDP-provided login URL * Download the SAML Metadata XML - The Metadata XML **must** be using RSA-SHA256 XML signatures