Connect an OPC UA server

Connect an OPC UA server to Synnax, with its login and security settings.

An OPC UA server makes the values of a PLC or a SCADA system available as nodes. In Synnax, an OPC UA server is one endpoint with its login and security settings. The read task and the write task add the nodes.

Prerequisites

Supported

WindowsmacOSLinuxNI Linux RTDocker

• A running Driver that can reach the server on the network. Synnax Desktop runs one for you.

Connect a server

from synnax import opcua

rack = client.racks.retrieve_embedded_rack()
device = client.devices.create(
    opcua.Device(
        name="Line 1 PLC",
        endpoint="opc.tcp://192.168.1.50:4840",
        location="opc.tcp://192.168.1.50:4840",
        rack=rack.key,
    )
)

const rack = await client.racks.retrieve({ name: "Node 1 Embedded Driver" });
await client.devices.create({
  key: crypto.randomUUID(),
  name: "Line 1 PLC",
  rack: rack.key,
  location: "opc.tcp://192.168.1.50:4840",
  make: "opc",
  model: "OPC UA server",
  configured: true,
  properties: {
    version: "2.0.0",
    connection: {
      endpoint: "opc.tcp://192.168.1.50:4840",
      securityMode: "None",
      securityPolicy: "None",
      certificateValidationDisabled: false,
    },
    read: { indexes: [], channels: {} },
    write: { channels: {} },
  },
});

Security

In the Security section, the Mode and the Policy protect the connection between the Driver and the server. Set them to values that the server accepts.

• Mode -> None, Sign, or Sign and encrypt.
• Policy -> the algorithms. When you change the mode from None, the Console selects Basic 256-bit with SHA-256. Select a deprecated policy only when the server supports nothing newer.

To see the settings that the server accepts, click Find endpoints next to Mode. The Driver asks the server for its endpoints, and the Console lists each mode and policy, most secure first, with the logins that each one accepts. Select one to set the Mode and the Policy. A policy that the Driver does not support shows as “not supported” and you cannot select it.

The other security fields show when the mode is not None. In Python and TypeScript, set a policy other than "None" when the mode is not "None". With the policy at "None", the Driver does not load the certificates, even when the mode is "Sign".

Client certificate

The Driver sends a certificate to the server. Select one of these:

• Driver certificate -> the default. Each Driver makes its own certificate, and all the servers that the Driver connects to get the same one. The dialog shows its thumbprint and its expiry date.
• Files on the Driver computer -> the paths of a certificate and a private key on the computer that runs the Driver. Use this when your site issues its own certificates. The key must not have a password, and the certificate must hold the application URI of the Driver.

Most servers reject a certificate that they do not know, and keep it in a list of rejected certificates. To make the server trust the Driver certificate:

1. Click Connect. The test fails with “Server rejected the Driver certificate”.
2. On the server, find the Driver certificate in the rejected list. Make sure that its thumbprint is the same as the one in the dialog, then trust it.
3. Click Connect again.

If the server has no rejected list, click (Download as DER) to save the certificate as a DER file, then add the file to the trust list of the server. For a server that needs PEM, convert the file that you downloaded, here driver.der:

openssl x509 -inform der -in driver.der -out driver.pem

The Driver certificate is valid for 3 years. 60 days before it expires, the Driver makes the next certificate and keeps using the current one. Once a day, the Driver connects to each secured server with the next certificate, so a server that does not trust it yet adds it to its rejected list. Trust it there, or click (Manage) in the dialog and download it under Renewal. The Driver uses the next certificate when all the servers accept it, or when the current one expires.

Regenerate replaces the certificate of the Driver with a new one. Use it only when the private key is no longer safe. All the servers must then trust the new certificate.

Server certificate

Each server has a certificate, and a device trusts one server certificate. The Driver connects only to a server that sends the trusted certificate.

• In the dialog, the first Connect fails with “Server certificate not trusted”. The dialog shows the certificate that the server sent, with its subject, thumbprint, and expiry date. Make sure that the thumbprint is the same as the one the server shows, then click Trust and connect. The dialog saves the certificate and connects again.
• A device made in Python or TypeScript without a server certificate trusts the certificate that the server sends on the first connection. The Driver saves that certificate to the device.
• When the server gets a new certificate, the device shows “Server certificate not trusted”. Open the device, compare the new thumbprint, and click Trust.

Validate server certificate

Validate server certificate is on by default. Turn it off only to troubleshoot a connection. When it is off, the Driver accepts any server certificate, and the device shows the warning “Connected without certificate validation”. Turn it on again when you finish.

Login

The Driver logs in to the server as an anonymous user, or with the Username and Password when you enter one of them. It cannot log in with a user certificate.

Connection options

The timeouts are in the Advanced section of the dialog. In TypeScript, the fields are in properties.connection in camel case, such as securityMode, clientCertificate, serverCertificate, certificateValidationDisabled, and clientTimeoutMs.

Security policies

Troubleshooting

• Failed to reach server

  Cause

  The Driver checks each server every 5 seconds, unless a task on the server got a reply since the last check. The status shows “Failed to reach server” when the Driver cannot connect. The description shows the reason.

  Fix

  1. Check the Endpoint, including the port.
  2. Make sure that the computer that runs the Driver can reach the server.

• The Driver paused new connections to the server after too many failed attempts in a row.

  Cause

  The Driver failed to connect three times in a row, so it waits 5 seconds before it tries again. Each further failure doubles the wait, up to 30 seconds. A successful connection resets it.

  Fix

  1. Fix the cause of the first error.
  2. Try again.

• Failed to configure encryption

  Cause

  The Driver could not use the certificate, the key, or the policy.

  Fix

  Select a policy that the server supports.

• Server certificate not trusted

  Cause

  The server sent a certificate other than the one that the device trusts, or the device trusts no certificate yet.

  Fix

  1. Open the device and click Connect.
  2. Make sure that the thumbprint in the dialog is the same as the one the server shows.
  3. Click Trust and connect.

• Server rejected the Driver certificate

  Cause

  The server does not trust the client certificate.

  Fix

  Trust the certificate on the server. See client certificate.

• Server certificate expired

  Cause

  The certificate of the server is not valid at the current time.

  Fix

  1. Renew the certificate of the server.
  2. Open the device, click Connect, and trust the new certificate.

• Failed to read client certificate

  Cause

  The Driver could not use the files in Certificate file and Private key file.

  Fix

  1. Make sure that the paths are correct on the computer that runs the Driver.
  2. Make sure that the key belongs to the certificate.
  3. Remove the password from the private key.

• Failed to load the Driver certificate

  Cause

  The Driver could not read, make, or save its certificate.

  Fix

  1. Make sure that the Driver can write to its data directory.
  2. Restart the Driver.

• Connected without certificate validation

  Cause

  Validate server certificate is off, so the Driver accepts any server certificate.

  Fix

  Turn on Validate server certificate when you finish troubleshooting.

• Server does not trust the next certificate

  Cause

  The Driver certificate expires soon, and the server does not trust the next one yet.

  Fix

  Trust the next certificate on the server before the date in the description. See client certificate.

• The URI specified in the ApplicationDescription does not match the URI in the certificate.

  Cause

  The URI in the certificate file is different from the URI that the server expects.

  Fix

  Create a certificate whose URI matches the server configuration.

• User does not have permission to perform the requested operation.

  Cause

  The server rejected the Username or the Password. Some servers show “The user identity token is valid but the server has rejected it.” for the same cause.

  Fix

  Enter a Username and a Password that the server accepts.

• The user identity token is not valid.

  Cause

  The server does not accept an anonymous login.

  Fix

  Enter a Username and a Password.

For other problems, see Troubleshoot hardware.