Okta SSO (SAML)
Overview
While Nucleus includes a comprehensive system for managing users and groups, customers may choose to use a 3rd party identity provider for managing access. This document details the steps needed to integrate Nucleus and Okta for Single Sign-On.
Prerequisites
To configure Okta for SSO, the following is required:
A configured and functional Okta tenant with a user that has administrative access
A stable and operational Enterprise Nucleus Server
An SSL/TLS certificate from a trusted Certificate Authority (CA) for the Nucleus SSO Gateway. (The entire certificate chain and private key is required.)
Access to create public DNS entries within your domain
Note
The file location examples shown in this document assume you are using the default installation path. Modify the file paths if you are using a custom location for your Nucleus SSO Gateway installation.
Part I: Pre-Configuration
Before configuring Okta or Nucleus for SSO, the following pre-configuration changes are needed:
Create a DNS entry for the Nucleus SSO Gateway which points to the IP Address of your Nucleus server. (Depending on your requirements, this may be a public or internal DNS entry.)
Warning
Configuring SSO may require network configuration changes (i.e., firewall changes). Please consult your IT/Information Security team for proper advisement.
Part II: Okta Configuration
Within the Okta Administrative Portal, expand the Applications menu, and click Applications:
Next click Create App Integration.
From the list of app integrations, choose SAML 2.0 and click Next.
Within (1) General Settings, complete the following:
App name: Omniverse Nucleus (example only)
App logo: Optional
App visibility: Enabled (Unchecked) by default
Click Next.
Within (2) Configure SAML, complete the following:
Single sign on URL: Append SSO URL with /result (e.g., https://sso.omniverse.nvidia.com/result)
Enable checkbox: Use this for Recipient URL and Destination URL
Audience URI: nucleus-auth
Name ID format: EmailAddress
Application username: Okta username
Update application username on: Create and update
Within the Attribute Statements (optional) area, add the following two statements:
Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Name format: URI Reference
Value: user.firstName
Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Name format: URI Reference
Value: user.lastName
Click Next.
Within (3) Feedback, keep the defaults and click Finish.
From within the Sign On tab, locate the Metadata URL within the SAML 2.0 Metadata details area. Copy this URL, open a new web browser window or tab, then paste and access it to display the required metadata. Right click the page within the web browser and choose Save Link (Page) As to download the metadata file in its native format.
Warning
Do not open this metadata file in your browser and copy/paste into a text file. This will convert line breaks into spaces and corrupt the file.
Click View Setup Instructions and make note of the following information:
Identity Provider Single Sign-On URL
Identity Provider Issuer
This information will be used in a later step.
Part III: Configuring Nucleus
Prior to configuring the Nucleus configuration files, upload the metadata file that was downloaded from the Okta portal and save it to this path:
/opt/ove/base_stack/saml/oktametadata.xml
Within the nucleus-stack.env
file, the following changes need to be made:
Enable the SSO functionality:
USE_SAML_SSO=1
Set the Nucleus SSO Gateway Address: (This address is provided by Okta.)
SSO_GW_ADDRESS=
Set the SSO Metadata file location: (This is the file from Step 1.)
FEDERATION_META_FILE=
Set the SAML IDP Login URL: (This address is provided by Okta.)
SAML_LOGIN_URL=
Set the text for the SSO button that will appear on the Nucleus log on screen:
SAML_SSO_NAME="Okta SSO"
Note
Any fields within the nucleus-stack.env
file that are not mentioned above should remain using their default configuration.
Configure the Nucleus SSO Gateway
Within the nucleus-sso-gateway.env
file, make the following changes: (This file is located in the /opt/ove/sso
directory if Nucleus was installed using the default installation path.)
Uncomment the End-User License Agreement (EULA):
# Uncomment to indicate your acceptance of EULA
ACCEPT_EULA=1
Specify the location of the SSL/TLS certificates and keys:
SSL_CERT=
SSL_KEY=
Note
It’s necessary to provide the full certificate chain and the Nucleus SSO Gateway requires all certificates to be contained within a single file and be in the following order (top to bottom): Domain Cert > Interim Cert(s) > CA/Root Cert.
If a password is required to decrypt the key, specify it here:
SSL_KEY_PASSWORD=
Make sure that your Nucleus SSO Gateway is running on TCP 443: (If required, the SSO Gateway may be run on a different port (i.e., TCP 444)):
SSO_GW_PORT=443
Before running the Nucleus SSO service, pull the necessary containers to ensure all required software is locally available:
sudo docker compose --env-file /opt/ove/sso/nucleus-sso-gateway.env -f /opt/ove/sso/nucleus-sso-gateway.yml pull
Once the software is pulled, it can be started:
sudo docker compose --env-file /opt/ove/sso/nucleus-sso-gateway.env -f /opt/ove/sso/nucleus-sso-gateway.yml up -d
Note
The above configuration assumes that SSL is being used for your Nucleus environment. If SSL is not being used, specify the no-ssl.yml configuration file.
Part IV: Testing
In your web browser, visit the URL for your Nucleus server, which should now display an Okta SSO login option:
Clicking the Okta SSO button will direct you to Okta for authentication. Once correct credentials are entered and the user is authenticated, Nucleus Navigator will appear.
Part V: Optional Configuration
Hiding Local Account Credential Fields
Once your Nucleus server is configured for SSO, the login dialog can be configured to hide the username, password, and Create Account link which then forces the user to log in only using the SSO provider.
To remove the extra credential fields, follow these steps:
Log into your Enterprise Nucleus Server and change to the directory where Nucleus is installed.
Using your preferred text editor, make the following change to
nucleus-stack.env
: (Change True to False.)
CREDENTIAL_UI_VISIBLE=false
Restart the Docker containers on your Enterprise Nucleus Server.
The login page for Nucleus will now only display the link for the SSO provider as shown in the example below:
Important
The login/password credential window can be accessed by adding /admin to the end of the URL when logging into Nucleus Navigator using a web browser. (e.g., https://omniverse.nvidia.com/omni/web3/admin).
Troubleshooting
If connections to your Nucleus server are failing, telnet to the SSO Gateway port from your computer. (By default, telnet is not enabled within Windows and is sometimes not installed on Linux distributions.)
If a connection refused or similar message is displayed, verify the following:
Ensure the Nucleus SSO Gateway service is running and the port configuration is correct.
Ensure there is not a local firewall running on the server and/or a firewall blocking connections.
To verify that your Nucleus SSO Gateway is configured correctly, visit the URL of the Nucleus SSO Gateway using your browser. If the configuration settings are correct, the following message will appear:
If you are using an NGINX proxy to provide TLS/SSL for Nucleus and are receiving a 414 Request-URI Too Large message when logging in with SSO:
Make the following changes within the nginx.ingress.router.conf file on your NGINX server:
server {
# Disable size limit on request bodies
client_max_body_size 0;
large_client_header_buffers 16 16k;
Once the change is made and the file is saved, restart the NGINX service and try again.