IMD SolutionComputing LibraryShop main store

How-to

Configuring TLS in the Node-RED Sparkplug node

Edge computing and IIoT Published 5 min read

Short answer

Set the Sparkplug node's broker Server URL to ssl:// followed by the broker hostname, and the Port to 8883. The connection negotiates TLS only when the broker presents a certificate chaining to a CA the Node-RED runtime already trusts and requests no client certificate; the editor exposes no fields for a self-signed trust anchor, client certificate, or private key, so those broker policies need a different client.

On this page
  1. What the editor exposes
  2. Configure the TLS connection
  3. Which broker policies the node can meet
  4. Worked example: prove the path before blaming the node
  5. Isolate the layer that fails
  6. When the broker requires mutual TLS
  7. Questions asked

The Sparkplug node reaches a TLS broker through its own broker configuration: set the Server URL to ssl:// followed by the broker hostname, set the Port to 8883, and deploy. That is the whole exposed capability, and it is enough when the broker presents a certificate that chains to a CA the Node-RED runtime already trusts and requests no client certificate. The editor exposes no field for a custom trust anchor, a client certificate, or a private key, so a self-signed server certificate or a mutual-TLS policy ends the handshake before MQTT starts. There the decision is to change the client, never to weaken the broker.

What the editor exposes #

The node covered here is the mqtt sparkplug device node from node-red-contrib-mqtt-sparkplug-plus; its documented path is to drag the device node into a flow and edit its MQTT broker connection. The Cirrus Link example client installs the node-red-contrib-sparkplug package with npm and reaches a broker-configuration screen the same way through its built-in examples under Import > Examples. Either way, the broker definition you can edit amounts to the connection fields: the Server URL and the Port.

The standard MQTT In and MQTT Out nodes are different. Their connection editor carries an Enable secure (SSL/TLS) connection option and an Add new tls-config… picker that opens the TLS configuration where the certificate elements live. The Sparkplug node's editor has neither, and it does not share the tls-config objects built for the MQTT nodes. That asymmetry is the entire TLS gap.

Configure the TLS connection #

  1. Read the broker before touching the flow. From the broker's own configuration, confirm which listener carries TLS, which port it binds, whether its certificate chains to a public CA, and whether it requests client certificates. This node can meet exactly one policy: server-authenticated TLS, a publicly CA-signed certificate, no client-certificate request.
  2. Double-click the Sparkplug device node and open its broker configuration for editing.
  3. Set the Server URL to ssl:// plus the broker hostname, written exactly as the hostname appears in the server certificate. A hostname mismatch fails the handshake even with a valid chain.
  4. Set the Port to the secure listener's port: 8883 in the documented working setup. If the broker binds its TLS listener elsewhere, enter that port instead.
  5. Deploy, then watch the node status and the broker connection log together, so a TLS rejection is not mistaken for a Sparkplug problem.

Which broker policies the node can meet #

Policy on the secure listener What the client must supply Decision
No TLS, plain MQTT nothing Connects, but Sparkplug payloads cross the network unencrypted; keep it off shared segments
TLS, public-CA server certificate, no client certificate requested scheme and port only Supported: ssl:// and port 8883
TLS, self-signed server certificate a configured trust anchor Not supported; the editor has no field for one
Mutual TLS, broker requests a client certificate client certificate and private key Not supported; use a different client

The second row is the only one the node satisfies on its own. The trust decision behind the last two rows is the same one made anywhere an industrial client meets a certificate; the OPC UA form of that problem is covered in troubleshooting CA-signed certificate trust errors.

Worked example: prove the path before blaming the node #

Illustrative values, not a measured result. An edge PC runs Node-RED with the Sparkplug package installed. The broker mqttgw.plant.example.com offers TLS on port 8883 with a certificate issued by a public CA, hostname matching, valid until 2026-06-30. The check is made on 2026-01-15.

Remaining certificate validity on the check date: January contributes 31 - 15 = 16 d, then February 28 d (2026 is not a leap year), March 31 d, April 30 d, May 31 d, June 30 d. Total 16 + 28 + 31 + 30 + 31 + 30 = 166 d.

Configuration: Server URL ssl://mqttgw.plant.example.com, Port 8883, deploy. Expected result on this setup: the node reaches its connected state and the broker log records the Sparkplug client session. Decision: with 166 d of validity left and a matching hostname, a failing handshake here is not an expired or mismatched certificate; confirm next that the listener is not requesting client certificates.

Isolate the layer that fails #

Observation Layer that stopped Action
No connection attempt shows in the broker log network path or listener Fix routing, firewall or listener binding; certificates cannot help
TCP opens, then the session drops during the handshake TLS Check the chain, the hostname match, and whether the broker requests a client certificate
Handshake completes, MQTT refuses the session MQTT authentication Correct credentials or ACL entries on the broker
MQTT connects, no Sparkplug data appears Sparkplug layer Check node configuration and client state handling

For the broker end of that work, the reference steps are in running a secure Mosquitto MQTT lab broker with Node-RED. A client that connects and is still refused over its state is the case in why a broker rejects your Sparkplug client over its STATE will. When the session is clean but data is still missing, trace the broker path the same way as when checking gateway data reaching Node-RED through an MQTT broker.

When the broker requires mutual TLS #

Commit to the boundary: the node cannot present a client certificate, and no URL or port change fixes that, because the broker asks for the certificate during the TLS handshake, before MQTT or Sparkplug exist. Two real options remain. Publish Sparkplug from a client that exposes certificate and key material, following the controller-side route in fixing CODESYS MQTT TLS peer verification failures. Or extend the open-source node package to add the missing fields. Do not lift the broker's client-certificate requirement to admit this node; that requirement is the one control proving who is connecting before MQTT authentication runs.

Questions asked

Can I reuse the tls-config from my MQTT In or MQTT Out node?

No. The standard MQTT nodes attach their TLS material through a tls-config object behind the Enable secure (SSL/TLS) connection option, and the Sparkplug node's broker editor neither offers that picker nor shares what it contains. Entries you build for the MQTT nodes stay with those nodes; pre-building one does not make it appear in the Sparkplug editor.

Does TLS depend on using port 8883 specifically?

No. The scheme in the Server URL is what selects TLS: ssl:// starts a TLS session on whatever port you enter. Port 8883 is the conventional secure MQTT listener, so it is the usual value, but the number that matters is the one the broker's TLS listener actually binds.

Our broker certificate comes from the company's own CA. Does that count as self-signed here?

In effect, yes. The handshake validates against the trusted CA list the Node-RED runtime carries, and an internal root is not on it. The editor gives you no field to install a private CA, so the connection fails exactly like the self-signed case; plan on a client that accepts a configured trust anchor.

The broker also requires a username and password. Does that change the TLS steps?

No. TLS completes first, and MQTT authentication runs inside the encrypted session afterwards. Keep the same Server URL and Port; wrong credentials produce an MQTT-layer refusal after a successful handshake, which shows up in the broker log as a rejected connect rather than a TLS error.

Why not turn off client-certificate checking on the broker?

Because that request is what proves each client's identity cryptographically. Dropping it so one node connects moves every client on the listener to username-and-password-only authentication, which is a real loss on an OT network. Keep the policy and publish Sparkplug from a client that can present a certificate and key.

Keep reading

  • How-to

    Run a secure Mosquitto MQTT lab broker with Node-RED

    Run Mosquitto on port 8883 with TLS, per-user passwords and an ACL that lets each team write only under lab/teamN/# and read all of lab/#, with a separate Node-RED user that reads everything. Distribute ca.crt only, and prove the ACL by publishing to another team's prefix and seeing nothing arrive.

    Edge computing and IIoT

  • How-to

    Harden a Node-RED OPC UA server exposing PLC tags

    A default Node-RED OPC UA server accepts any client that can reach its port until three changes land: set message security mode to SignAndEncrypt with the Basic256Sha256 policy, remove mode None and anonymous login, and admit clients only through application-certificate trust lists. Those three changes are the whole decision; the rest is execution.

    Edge computing and IIoT

  • Troubleshooting

    Fix CODESYS MQTT TLS peer verification handshake failure

    Enabling peer verification in the MQTT client's TLS context fails because the controller has no trust anchor for the broker's certificate chain. Import the issuing CA certificate into the runtime's trusted certificate area through the security screen; the client identity .pfx does not provide that trust. A TCP_Init error is an earlier socket-layer fault, so check endpoint settings before touching certificates.

    Edge computing and IIoT