---
description: >-
  The OPC UA connector allows NovaCura Flow to communicate with OPC UA servers.
  This page explains how to configure and use the connector.
---

# OPC UA Connector

***

## Configuration

The OPC UA Connector utilizes session caching for improved performance. A session is created for each connector configuration and remains active until the specified session timeout is reached. You can configure the following settings for the OPC UA Connector:

### **Main Settings:**

* **URL to OPC UA Server:**\
  This required field specifies the address of the target OPC UA server. Use the format `opc.tcp://[server address]:[port]/[optional path]`.\
  Example: `opc.tcp://10.16.1.100:4840/UA/SampleServer`.
* **Use Security:**\
  This setting determines whether to establish a secure connection to the OPC UA server.
* **Cache Metadata:**\
  Enable this option to cache metadata from the OPC UA server, which can improve performance.

***

### **Identity**

Expand this section to configure the authentication method used to connect to the OPC UA server. You can choose from several modes:

* **Anonymous:**\
  No credentials are required for authentication.
* **Username:**\
  Connect to the server using a username and password.
* **Certificate:**\
  Authenticate with an X509 certificate. This method requires providing the certificate data or referencing a certificate stored in the system.
* **Issued Identity Token:**\
  Utilize a pre-existing issued identity token for authentication.

***

### **Application**

This section allows for fine-grained control over various aspects of the OPC UA client application's behavior and security. Each sub-section below provides settings to customize the interaction with the OPC UA server.

#### **Application Identity and Configuration**

* **Application URI:** A unique Uniform Resource Identifier (URI) that identifies your application to the OPC UA server. This field typically follows a specific format; consult your server's documentation for the correct syntax. A common pattern is `urn:localhost:applicationName`.
* **Application Name:** A human-readable name for your application, displayed on the OPC UA server.
* **Product URI:** A URI that identifies the product this application is part of.

#### **Transport Quotas**

These settings define limits on the size of data exchanged during communication with the OPC UA server. Adjusting these values can impact performance and stability. Excessively large values can consume more resources, while excessively small values may lead to communication failures. Consult the OPC UA specification and your server's documentation for recommendations.

* **Operation Timeout:** Specifies the maximum time (in milliseconds) allowed for a single operation to complete. If the operation does not finish within this timeframe, it will time out. Default is 120000 milliseconds (2 minutes). Increasing this value may improve reliability, particularly in high-latency networks. However, excessively long timeouts can introduce delays.
* **Maximum String Length:** Sets the maximum length (in characters) of a string that can be transmitted in a single message. The default value is 65535 characters.
* **Maximum Byte String Length:** The maximum length (in bytes) of a byte string that can be transmitted in a single message. The default value is 1048560 bytes (1 MB).
* **Maximum Array Length:** Defines the maximum number of elements allowed in an array that can be transmitted. The default is 65535 elements.
* **Maximum Message Size:** This setting limits the maximum size (in bytes) of a single message, affecting the overall size of data exchanged in one communication. The default value is 2097152 bytes (2 MB).
* **Maximum Buffer Size:** Specifies the maximum size (in bytes) of the internal buffer used for data exchange. The default is 65535 bytes.
* **Channel Lifetime:** Defines the duration (in milliseconds) for which a secure channel remains active. Once this timeout elapses, a new secure channel is established. The default value is 30000 milliseconds (30 seconds).
* **Security Token Lifetime:** The maximum lifetime (in milliseconds) of the security token used for authentication. This sets how long a connection remains valid before re-authentication is required. The default is 3600000 milliseconds (1 hour).

#### **Trace Configuration**

This section configures trace logging, which is invaluable for debugging and troubleshooting connection issues. Trace logs record detailed information about the connector's operations.

* **Output File Path:** Specify the full path to the file where trace logs will be written. Ensure the connector has write permissions to this location. If the file already exists, its contents may be overwritten or appended depending on the `Delete on Load` setting.
* **Delete on Load:** Check this option to delete the existing trace log file specified in `Output File Path` when the connector starts. This ensures the log file contains only data from the current session. If unchecked, new log data will be appended to the existing file.
* **Trace Masks:** Select the types of trace messages to be recorded. Choose from the following options:
  * **None:** No trace messages will be logged. This is the default setting.
  * **Error:** Logs only error messages.
  * **Information:** Logs informational messages.
  * **Stack Trace:** Includes stack traces with error messages. Useful for pinpointing the source of errors.
  * **Service:** Records messages related to OPC UA service calls.
  * **ServiceDetail:** Includes more detailed messages about service calls.
  * **Operation:** Logs messages related to individual operations performed by the connector.
  * **OperationDetail:** Logs very detailed messages about the operations.

**Important Considerations:**

* **Verbosity:** Selecting verbose trace masks increases the verbosity and file size of the log. Start with the `Error` mask to isolate issues, and then incrementally add more masks for more detailed diagnostics.
* **Security:** Be cautious about the level of detail recorded in trace logs if sensitive information is transmitted.

#### **Client Configuration**

This section configures parameters specific to the OPC UA client's behavior and interaction with the server.

* **Default Session Timeout:** Specifies the default inactivity timeout (in milliseconds) for OPC UA sessions. If a session remains inactive for this duration, it will be closed, and a new session will be created upon the next request. The default value is 60000 milliseconds (60 seconds).
* **Endpoint Cache File Path:** Specifies the file path to store cached endpoint information. Caching endpoints can significantly improve the speed of connecting to the OPC UA server. The connector will attempt to load endpoint information from the specified file upon initialization. If the file does not exist or the path is invalid, the connector will proceed without caching.
* **Minimum Subscription Lifetime:** Defines the minimum duration (in milliseconds) for OPC UA subscriptions. Subscriptions are used to monitor changes to server-side variables. Setting a minimum lifetime prevents excessively short-lived subscriptions, which can lead to performance issues. The default value is 10000 milliseconds (10 seconds).

**Important Considerations:**

* **Caching:** While endpoint caching improves performance, ensure the chosen path is accessible and appropriate for persistent storage.
* **Subscription Lifetime:** The value for `Minimum Subscription Lifetime` should be chosen based on the frequency of updates and the required responsiveness of your application.

#### Security Configuration

The Security Configuration section defines critical parameters for authentication and secure communication between the OPC UA client and server. Properly configuring these settings is essential for maintaining security standards.

* **Send Certificate Chain:** Check this option to have the client send the complete certificate chain to the server during the initial handshake. This aids in server validation of the client’s identity.
* **Add Application Certificate to Trusted Store:** Enabling this option will automatically add the application certificate to the local trusted certificate store, streamlining the process of establishing secure sessions.
* **Minimum Certificate Key Size:** Sets the minimum acceptable key size for certificates (in bits). The default value is 2048 bits, in line with current security standards that recommend using key sizes of at least 2048 bits.
* **Reject SHA1 Signed Certificates:** When enabled, this setting prevents the use of certificates signed with the SHA-1 hashing algorithm, which is considered insecure.
* **User Role Directory:** Specifies the directory that contains role-based security information used for authorization. This setting may be relevant for applications needing additional role management.
* **Automatically Accept Untrusted Certificates:** Enabling this option allows the application to automatically accept certificates that are not present in the trusted store. Exercise caution with this setting to avoid security risks.
* **Nonce Length:** Defines the length of the nonce used for authentication. The default value is 32 bits. A nonce is a random or semi-random number issued for one-time use to help maintain secure sessions.
* **Application Certificate:** This field displays the current certificate assigned to the application. You can click "EDIT" to view or modify the application certificate settings.

***

#### Application Certificate Edit Dialog

The "Edit Application Certificate" dialog allows you to configure settings related to the application's X.509 certificate, which is vital for establishing secure connections.

* **Certification Load Mode:** Determines how the application certificate is loaded. It can be set to:
  * **Referenced:** Loads the certificate from a specified store path.
  * **Embedded:** Loads the certificate from within the application.
* **Store Type:** Specifies the type of certificate store. Common options include:
  * **Directory:** Indicates a file system directory where certificates are stored.
  * **X.509 Store:** Suitable for system-level certificate stores.
*   **Store Path:** The file system path to the directory or store where the application certificate is located. Example:

    ```
    C:\ProgramData\OPC Foundation\CertificateStores\MachineDefault
    ```


* **Subject Name:** Displays the subject name associated with the application certificate, typically following the format `CN=applicationName`.
* **Thumbprint:** The unique identifier for the application certificate, used to verify its integrity and authenticity.
* **Validation Options:** This section provides additional options for customizing how certificates are validated, with the ability to suppress certain validation errors. The following options may be available:
  * **Default:** Uses the default validation behavior.
  * **Ignore expired certificates:** Suppresses errors for expired certificates.
  * **Ignore mismatches between the URL and DNS names:** Allows flexibility in certificate name validation.
  * **Ignore errors when unable to check revocation status:** Bypasses errors relating to the revocation status check.
  * **Attempt to check the revocation status online/offline:** Options for checking whether a certificate has been revoked.
  * **Never trust the certificate:** Prevents the application from trusting the certificate, effectively ignoring it in terms of validation.

#### Certificate Management

The Certificate Management section allows you to view, configure, and manage various certificate stores essential for secure communication. The following types of certificates can be managed:

* **Trusted User Certificates:** These certificates are used to authenticate users.
* **User Issuer Certificates:** Certificates from issuers that authenticate users.
* **HTTPS Issuer Certificates:** Certificates used specifically for securing HTTPS connections.
* **Trusted Peer Certificates:** Certificates trusted for peer communication in a network.
* **Trusted Issuer Certificates:** These certificates are from trusted Certificate Authorities (CAs) and are used to verify the authenticity of other certificates.
* **Trusted HTTPS Certificates:** Certificates that are trusted for HTTPS communications.
* **Rejected Certificate Store:** This store contains certificates that have been explicitly rejected and will not be trusted.

**Expandable Certificate Stores**

Each of the above certificate categories has the following settings:

*   **Store Path:** Displays the location where the certificates for that category are stored. For example, the Trusted User Certificates store path may look like:

    ```
    C:\ProgramData\OPC Foundation\CertificateStores\UA Applications
    ```
* **Validation Options:** Each certificate store has the same validation options, which can be edited by clicking "EDIT." The available options include:
  * **Default:** Uses the default validation behavior.
  * **Ignore expired certificates:** Suppresses errors for expired certificates.
  * **Ignore mismatches between the URL and DNS names:** Allows flexibility in certificate name validation.
  * **Ignore errors when unable to check revocation status:** Bypasses errors relating to revocation checks.
  * **Attempt to check the revocation status online/offline:** Options for checking whether a certificate has been revoked.
  * **Never trust the certificate:** Prevents the application from trusting the certificate.
* **Trusted Certificates:** This section lists the certificates currently trusted in that store. You can add new trusted certificates by clicking the **ADD** button. The **Rejected Certificate Store** does not have this section for obvious reasons.

**New Trusted Certificate Dialog**

When you click **ADD** to create a new trusted certificate, the **New Trusted Certificate** dialog opens, allowing you to configure the following:

* **Certification Load Mode:** Determines how the new trusted certificate is loaded, typically set to **Referenced** or **Embedded**.
* **Store Type:** Defines the type of store for the certificate, such as **X509Store** or **Directory**.
* **Store Path:** Specify the location where the certificate will be stored.
* **Subject Name:** The subject name associated with the trusted certificate, typically in the format `CN=subjectName`.
* **Thumbprint:** A unique identifier for the certificate useful for verification.
* **Validation Options:** Allows customization of how this specific certificate will be validated. Clicking **EDIT** opens the options as discussed earlier.

**Important Considerations:**

* **Security:** Carefully manage trusted certificates. Only add certificates from sources you trust.
* **Regular Audits:** Regularly review and updated trusted certificates to avoid potential security risks.

#### Transport Configurations

The Transport Configurations section allows users to define how the OPC UA client communicates with servers through specific transport settings. Proper configurations ensure effective and reliable communication using desired protocols.

**Adding a New Transport Configuration**

To add a new transport configuration, click the **ADD** button. This will open the **New Transport Configuration** dialog, where you can specify the following settings:

* **URI Scheme:** Enter the URI scheme that specifies the transport protocol used, such as `opc.tcp` for OPC UA over TCP.
* **Type Name:** Provide a name for the transport configuration to identify it within the system.

By clicking **OK**, the new transport configuration will be saved.

#### **Importing and Exporting Configurations**

Within the Configuration Editor, you will also find the **Load from file…** and **Save to file…** buttons, which facilitate the management of application configurations:

* **Load from File:** Use this option to import previously saved application configurations from a file. This feature is helpful for quickly applying a known working configuration or sharing configurations between instances.
* **Save to File:** Click this option to export the current application configurations to a file. This allows you to back up your settings or transfer them to another connector instance.

**Important Considerations:**

* Ensure that URI schemes and type names strictly adhere to the protocols and conventions used by your OPC UA server.

***

### Default Session

This section defines the session behavior for the OPC UA connector. Proper configuration of these settings ensures effective communication with the OPC UA server.

**Session Configuration Options:**

* **Session Name:**\
  Assign a custom name to the session. This is optional and can be used for clarity in identifying the session within your application.
* **Session Timeout:**\
  Specify the session's inactivity period (in milliseconds) before a new session is created. The minimum allowed value is 60000 milliseconds (60 seconds). If the session is inactive for this duration, the connector will establish a new session upon the next operation.
* **Operation Timeout:**\
  Define the maximum time (in milliseconds) the connector waits for an operation to complete before timing out. The default value is 5000 milliseconds (5 seconds). This setting is crucial for managing long-running operations and can be adjusted based on the expected response time of your server.
* **Update Before Connect:**\
  Enable this option to ensure the connector updates its internal node cache before establishing a connection with the server. This ensures that the connector has access to the latest data from the OPC UA server upon connection.
* **Check Domain:**\
  Specify whether the server's domain should be validated during the connection process. Enabling this option helps to ensure that the connector is communicating with the correct server, increasing security by preventing man-in-the-middle attacks.

**Saving Changes**

After configuring the session options as desired, click the **Save** button to apply the changes. If you wish to cancel the operation, click **Cancel**.

***

### **Enable Tracing**

Activate this option to enable tracing for debugging purposes. This can help identify issues in the communication between the connector and the OPC UA server.

***

## Note on Session Timeout

When the session timeout is reached, the connector automatically creates a new session. The old session is eventually removed. During this transition period, it is possible to have two active sessions for the same connector configuration. This design ensures a smooth transition without interrupting data exchange.

***

## Further Information

Please refer to the official OPC UA specification for more detailed information on configuring and using the OPC UA protocol. [OPC UA Specification Link](https://reference.opcfoundation.org/)
