Okta SSO¶

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 Nucleus Server running release 2022.1.0 or greater
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.firstNam
- 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 Identity Provider metadata link within the SAML 2.0 area. Right click the link and choose Save Link As to download the metadata file.

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 certificate.

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

You may need to provide the full certificate chain, depending on your issuing Certificate Authority (CA). The Nucleus SSO Gateway requires all of your certificates to be contained within a single file, and be in the following order (top to bottom): Domain Cert > Interim Cert > CA 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:

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/base_stack/nucleus-stack.env -f /opt/ove/base_stack/nucleus-stack-ssl.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:

Using a Custom SSO Button Icon¶

If it’s desired to use a custom SSO button icon, 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:

# Add the URL of where the image is hosted.  (e.g., https://www.nvidia.com/images/sso_icon.png)
SAML_SSO_IMAGE=

Additionally, make the following change to nucleus-stack-ssl.yml or nucleus-stack-no-ssl.yml: (Depending on the use of SSL or not.)

# Uncomment (and set to valid URL) if custom SSO
# icon is desired
SAML_SSO_IMAGE: ${SAML_SSO_IMAGE}

Restart the Docker containers on your Enterprise Nucleus Server.

The SSO button will now display your preferred icon as shown in the example below:

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.