Skip to main content

Security policies and certificates

Goal​

Enable secure endpoints. The Function-node API exposes two declarative knobs — securityPolicies and securityModes — on bootstrapServer({...}) from Creating an OPC UA server. Trust-store, server-certificate, and X.509 user-certificate management are handled by the palette itself; you do not configure them from a Function node.

One application: one server, many clients, one PKI

A Node-RED instance running the palette is one OPC UA application of type ClientAndServer: one server and as many client connections as your flows open, all sharing one PKI, one ApplicationUri and one application certificate.

That is exactly what OPC UA expects of a ClientAndServer application, and it pays off:

  • One identity to trust. A peer that trusts your Node-RED instance trusts it in both directions: when your flows connect to it as a client, and when it connects to your server. One certificate to hand over, one entry in its trust list.
  • One trust store. Trusting a peer certificate (moving it from rejected to trusted) applies to your client connections and your server at once. There is no second store to keep in sync, and the folder paths are reported by the server-info Function.
  • Pull certificate management (GDS). The instance can enrol itself at a Global Discovery Server and renew its certificate on its own, from the palette's Certificates page. The GDS registers it as ClientAndServer, and the certificate it issues serves both sides.
  • Push certificate management, as soon as the server is on. The server exposes the standard ServerConfiguration object, so an administrator or a GDS can push a new certificate, a new private key or new trust lists over OPC UA (CreateSigningRequest, UpdateCertificate, TrustList). Because the PKI is shared, a pushed certificate renews your client connections too, and they never end up on a key that no longer matches.

This is also why an instance runs one server: a second one would have to serve the same ApplicationUri and certificate from another address space. See Scaling and limits.

securityPolicies and securityModes are part of the config-identity hash, so changing them in the boot Function and redeploying triggers an automatic teardown-then-rebuild. To force a rebuild without changing config (e.g. after editing the trust store on disk), pass forceRebuild: true on the next call.

Add security settings​

const sterfive = global.get("sterfive");
if (!sterfive) {
    node.error("global.get('sterfive') is not set — is the Sterfive OPC UA palette loaded?");
} else {
    const { bootstrap, opcua } = sterfive;
    const { bootstrapServer } = bootstrap;

    const cfg = msg.config || {};

    const handle = await bootstrapServer({
        port: cfg.port ?? 4840,
        endpoint: cfg.endpoint || "node-red-server",
        nodesets: ["standard"],
        securityPolicies: [
            opcua.SecurityPolicy.None,
            opcua.SecurityPolicy.Basic256Sha256,
        ],
        securityModes: [
            opcua.MessageSecurityMode.None,
            opcua.MessageSecurityMode.Sign,
            opcua.MessageSecurityMode.SignAndEncrypt,
        ],
        onPopulate: (addressSpace, exposed) => {
            const ns = addressSpace.getOwnNamespace();
            exposed.myVariable = ns.addVariable({
                organizedBy: "RootFolder",
                nodeId: "s=MyDynamicVariable",
                browseName: "MyDynamicVariable",
                dataType: "Double",
                value: { dataType: opcua.DataType.Double, value: 0.0 },
            });
        },
    });

    flow.set("$myVariable", handle.exposed.myVariable);
    flow.set("$opcuaHandle", handle);

    node.send({ payload: `OPC UA Server running at ${handle.server.getEndpointUrl()}` });
}

The server advertises the cartesian product of allowed (policy, mode) pairs as separate endpoints. Clients pick one at session creation.

Trusting client certificates​

The palette manages a single shared certificate store, the same one your client connections use:

  1. A client connects for the first time over a secure mode. Its certificate lands in the rejected folder.
  2. Move (or copy) the certificate from the rejected folder into the trusted folder.
  3. Subsequent connections from that client succeed.

The exact folder paths and the server's own certificate file path are reported by bootstrap.getServerInfo(handle.server).certificates. They include:

  • rejectedFolder — incoming unknown client certificates land here.
  • trustedFolder — move trusted client certificates here.
  • privateKey / publicKey — the application's own certificate pair, used by the server and the client connections alike.
  • userTrustedFolder / userRejectedFolder — same scheme for X.509-based user authentication, kept in a separate userPki directory.

The palette also installs the OPC UA push-certificate-management service on the server, so admin clients can rotate the certificate over the wire without restarting Node-RED.

The application certificate​

The server and the client connections use one certificate, PKI/own/certs/certificate.pem, with one private key. Its ApplicationUri is the instance's own: generated once and kept in instance-id.json next to the PKI folder, or set with the OPCUA_APPLICATION_URI environment variable. The server advertises that URI, and the applicationUri field of bootstrapServer cannot change it.

If none exists yet, a self-signed certificate is generated on first use. That is fine for development. For production, have it issued by a CA:

  • Pull: enrol the instance at a GDS from the palette's Certificates page; the issued certificate is installed and renewed automatically.
  • Push: let a GDS or an administrator push it to the running server (CreateSigningRequest, then UpdateCertificate).
  • By hand: create a signing request and upload the signed certificate from the Certificates page.

Whichever way, the new certificate takes effect for the server and the client connections.

Upgrading from an earlier version

Earlier versions gave the server a certificate of its own, under the URI urn:node-red-server shared by every installation, and the clients client_certificate.pem. On first start, the client certificate becomes the application certificate and the old files are kept aside in PKI/own/certs/ under a timestamped name. OPC UA clients that trusted the old server certificate must trust the application certificate instead.

Notes​

  • Certificates are required for Sign and SignAndEncrypt. None works without them.
  • Username/password authentication over MessageSecurityMode.None sends credentials in cleartext — combine with at least Sign.
  • Disabling SecurityPolicy.None is the strict-secure default, but it breaks browsers and naive clients that probe with no security first.

Next step​

Continue with a structured namespace layout.

Further reading​

For more tips and examples, see the Sterfive book node-opcua by example.