How-to
Configuring TLS in the Node-RED Sparkplug node
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
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 #
- 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.
- Double-click the Sparkplug device node and open its broker configuration for editing.
- 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. - Set the Port to the secure listener's port:
8883in the documented working setup. If the broker binds its TLS listener elsewhere, enter that port instead. - 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.