SSL Configuration

Enterprise Nucleus Server does support SSL. To be more precise, most of SSL support is within Clients - though server requires a few configuration tweaks too.

An explanation of basic design of SSL support is warranted prior to proceeding to setup. We recommend reading this entire document prior to attempting to configure SSL with Nucleus.

SSL: Basic Design within Omniverse Ecosystem

All interaction between Clients and Nucleus are via either WebSockets, or HTTP - and therefore, SSL can be used to secure the transport layer.

Omniverse Clients can support both SSL and non-SSL connections: and they detect (and prefer) SSL automatically.

Nucleus Enterprise Server, however, does not concern itself with actual SSL termination. This means that even though your deployment can be configured with SSL, Nucleus itself will not “talk” SSL: it will still be listening on series of ports, opened as insecure HTTP or WebSocket endpoints.

This is on purpose: there are many good SSL termination solutions out there, and we don’t want to reinvent the wheel.

Instead, we rely on a reverse proxy for SSL connections. Clients connect to said proxy via SSL, and it forwards their requests to Nucleus over regular, non-secure connections. We call this proxy an Ingress Router. If this rings a bell in context of Kubernetes, it’s not a mistake: we basically do the same thing as what Kubernetes does with Ingress Controllers and Ingress objects.

../../../_images/prod_nucleus_ssl_arch.png

Non-SSL Client would connect to various Nucleus Components directly - on their ports (i.e., 3009, 3030, etc). With SSL however, Clients connect to a host - ie, https://my-nucleus.my-company.com - which is where the Ingress Router should be configured. Ingress Router examines the path of the request - and routes (reverse-proxies) a Client based on that path. We use the term Path-Based Routing, or PBR, to define this idea.

If a non-SSL Client desires to talk to Nucleus API for example, she would open a connection to my-nucleus-host.my-company.com, port 3009. With SSL (and PBR), she will instead connect to https://my-nucleus.my-company.com/omni/api. Host portion of this URL will lead her to the SSL termination point (Ingress Router), and path (/omni/api) will indicate to Ingress Router that her request should be reverse-proxied to Nucleus’s port 3009 (note how paths correlate to ports on the diagram above).

Note that Clients are such that paths needn’t be specified - just like ports, Clients know how to handle proper paths. In other words, when connecting to a SSL/PBR-enabled Nucleus, using just the hostname is sufficient.

Setting up Nucleus with SSL

Given the above description, in order to enable SSL for Nucleus, one needs to:

  • Configure appropriate network topology

  • Configure a reverse proxy to act as an Ingress Router

  • Configure the Nucleus Base Stack to be aware of the Ingress Router

Network Topology

Given that Nucleus itself does not terminate SSL, if any measure of real security is desired, Nucleus should be placed in a network that is not accessible by Clients.

A host to run the Ingress Router should be able to freely access Nucleus, and be accessible to Clients on ports 80 and 443 (latter can be changed, but we don’t recommend it).

Configuring Ingress Router

Any reverse proxy can act as an Ingress Router, provided it supports WebSockets, HTTP, and SSL. We use NGINX.

To make the setup easier, we ship a sample section of NGINX config file with the install artifact. This config file defines each “route” (path - location{}, basically) - with correct reverse proxying rules.

It’s designed to be included into your NGINX configuration’s http{} section and defines two servers: one on port 80 (to redirect to SSL and serve an internal endpoint), and one on port 443, where the Ingress Router’s SSL parameters and routes are configured.

As always, please review and adjust the config accordingly - at a minimum, you will need to include correct hostnames and provide SSL configuration options.

Warning

Currently, Omniverse Clients (Apps and Connectors) can only handle certificates with validated trust chains - in other words, a machine they’re running on has to trust Ingress Router’s cert. Clients do not have a clean warning of cert validation failure, and a button to bypass this failure. Instead, they will just fail.

Therefore, while self-signed certs or certs with mismatching hostnames will work in a browser (after skipping validation), they will not work in Clients.

Put another way, a cert you use in your Ingress Router has to be valid and acceptable to all machines that are intended to be Clients to this Router.

Even if not planning to use NGINX in production, we highly recommend trying it first as a reference setup. Once that works, that setup can be copied into whichever reverse proxy you are planning on using.

Configuring your Base Stack

Once your Ingress Router is up, your base stack will need to be re-configured and re-deployed with SSL-aware configuration (it mainly has to do with changes to internal Nucleus layout in the Discovery service).

Refer to your artifact’s .env file, where configuration options and other details are documented.

Verifying SSL

Once everything is configured, use the same method as you would when validating your base stack deployment, except that direct your browser to the hostname of your Ingress Router, and in addition ensure that SSL termination works properly (i.e., the cert you get is what you expect, the browser “sees” HTTPS, redirects worked properly, etc).