Certificates and HTTPS

What you get out of the box

A new Nexus listens on two ports:

Port	Protocol	Certificate
8080	HTTP	none — traffic is in the clear
8443	HTTPS	a self-signed certificate Nexus generates on first start

Both are open by default. Plain HTTP is there so first contact with a new Nexus does not begin with a browser security warning, and so Studio and Lens can list projects on a Nexus instance nobody has configured yet.

The self-signed certificate lands in certs/ inside the data directory.

A self-signed certificate is encryption without identity

Traffic on 8443 is encrypted from the first boot, which is worth having. But nobody can tell your Nexus from an impostor, and every browser warns. Install a real certificate before Nexus carries production traffic.

Installing a real certificate

1. Obtain a certificate and private key in PEM format for the name people will actually type — the hostname in the browser's address bar, not the machine's internal name.
2. Copy both onto Nexus, somewhere only the service account can read.
3. Point Nexus at them in its configuration file (where is it?):

{
  "nexus": {
    "tlsCertPath": "C:\\ProgramData\\Raylux\\certs\\nexus.crt",
    "tlsKeyPath":  "C:\\ProgramData\\Raylux\\certs\\nexus.key"
  }
}

4. Restart Nexus.
5. Browse to https://<name>:8443/ and confirm the browser is satisfied.

Include the full chain

If your certificate is issued by an intermediate authority, the certificate file must contain the full chain — your certificate first, then the intermediates. A chain that is complete in a browser you have already visited but incomplete on the wire is a classic source of "it works on my machine".

Turning off plain HTTP

Once HTTPS works, close the cleartext port:

{
  "nexus": {
    "httpDisable": true
  }
}

Restart, and Nexus serves HTTPS only. Do this on any Nexus reachable from a network you do not control.

If you set a single port only

Nexus will not silently move HTTPS to make room for HTTP. If the configuration gives it nowhere distinct to put a cleartext listener, it stays HTTPS-only. An existing Nexus therefore cannot become cleartext just because it restarted on a newer build.

Behind a reverse proxy

If you terminate TLS at nginx, IIS or a load balancer, you can have Nexus serve plain HTTP to the proxy only:

{
  "nexus": {
    "tlsDisable": true,
    "bindAddress": "127.0.0.1"
  }
}

Binding to loopback matters: without it, tlsDisable means an unencrypted Nexus listening on every interface.

Your proxy must send X-Forwarded headers

Nexus uses their presence to tell a local request from a remote one — which is what stops a proxy handing the no-secret first-run path to the whole network. Any standard proxy configuration sets them.

Pass the original host, or list the address

Spectrum screens get their live values over a WebSocket. Nexus accepts that connection from a browser only when the page's address (its origin) matches the host the browser asked for. It reads that host from the Host header, or from X-Forwarded-Host when a proxy sets it. This stops a page on another site from opening a live connection through an operator's browser.

A proxy that replaces Host with its own upstream address and sets no X-Forwarded-Host breaks that match. nginx does this by default: proxy_pass sends Host: 127.0.0.1:8088. Every Spectrum screen then shows This address is not allowed to connect, and the Nexus log has a Refusing a WebSocket warning naming the refused origin.

Fix it in either place:

• In the proxy (recommended). Pass the browser's host through. For nginx:

  location / {
      proxy_pass         http://127.0.0.1:8088;
      proxy_http_version 1.1;
      proxy_set_header   Upgrade           $http_upgrade;
      proxy_set_header   Connection        "upgrade";
      proxy_set_header   Host              $host;
      proxy_set_header   X-Forwarded-Host  $host;
      proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
      proxy_set_header   X-Forwarded-Proto $scheme;
  }

  If the public address uses a port other than 443 or 80, use $host:$server_port for X-Forwarded-Host.

• In Nexus. Open ConfigHub → Nexus Settings → Allowed origins, add the address operators type in their browser (for example https://plant.example, or https://plant.example:8443 with a non-standard port) and select Save. It takes effect for the next connection. No restart is needed. Each entry is an exact origin: http:// or https://, a host, and an optional port. Wildcards and paths are refused. Enter an international host name in its punycode form (https://xn--mnchen-3ya.example), which is what browsers send. An IPv6 address is stored in the short form browsers use, so https://[2001:db8:0:0:0:0:0:1] becomes https://[2001:db8::1]. The setting is stored as nexus.allowedOrigins in the project file:

  {
    "nexus": {
      "allowedOrigins": ["https://plant.example"]
    }
  }

Changing the list needs the Nexus configuration permission, and each change is recorded in the audit log as ALLOWED_ORIGINS_CHANGE. Studio's own connection sends no origin and is not affected. Lens shows Spectrum pages, so a Lens pointed at the proxy's address follows the same rule as a browser.

Enforce or warn only

The same card has an Origin check setting with two modes:

• Enforce refuses a connection from any address that is not this gateway's own and not in the list. A new installation starts here.
• Warn only lets that connection through and logs an Origin check is set to warn only warning naming the address. The warning repeats at most once every five minutes per address. A gateway upgraded from a release that had no origin check starts in this mode, so a plant that is already behind a proxy keeps its screens after the upgrade.

Under Seen from these origins the card lists the addresses whose connections did not match since Nexus started (the last 20), with how often and when each was last seen. Select Add next to an address that belongs to your plant, then Save. When every address operators use is listed, select Enforce. Both switches take effect for the next connection, with no restart, and are recorded in the audit log as ORIGIN_CHECK_CHANGE. The mode is stored as nexus.originCheck ("enforce" or "warn"). Any other value is treated as "enforce".

WARNING

Warn only accepts a connection from a page on any website, so a page on another site can read live values through an operator's browser. Use it only while you find the addresses to list.

Certificate trust in Studio and Lens

Studio and Lens do not use the operating system's certificate store for Nexus instances. The first time they connect they show you the certificate and ask you to accept it, then remember that exact certificate.

If it changes later they ask again. On a planned certificate renewal, accept it. If you are asked unexpectedly, stop and find out why before accepting.