Merge pull request #314389 from dominicbetts/aio-opcua-fixes

AIO: OPC UA updates and fixes

Author: prmerger-automator[bot]

articles/iot-operations/discover-manage-assets/howto-configure-opc-ua-certificates-infrastructure.md

@@ -295,3 +295,52 @@ Like the previous examples, you use a dedicated Kubernetes secret to store the c
     ```
 
 Now that the connector for OPC UA uses the enterprise certificate, don't forget to add the new certificate's public key to the trusted certificate lists of all OPC UA servers it needs to connect to.
+
+## Configure certificate subject alternative names
+
+The connector's self-signed certificate automatically includes the application URI and the local hostname in the Subject Alternative Name (SAN) extension. If OPC UA servers access the connector through other hostnames or IP addresses, you need to add those identities to the SAN. To learn more about SAN and when you need custom entries, see [Certificate subject alternative name](overview-opc-ua-connector-certificates-management.md#certificate-subject-alternative-name).
+
+> [!NOTE]
+> This configuration only applies to the connector's self-generated certificate. If you use an enterprise grade certificate, configure the SAN entries when you generate that certificate externally. For more information, see [Configure an enterprise grade application instance certificate](#configure-an-enterprise-grade-application-instance-certificate).
+
+To add custom DNS names, IP addresses, or both, add the `SubjectAlternativeDnsNames` and `SubjectAlternativeIpAddresses` properties to the connector's `SecurityPki` configuration in the `additionalConfiguration` field of the connector's deployment:
+
+```json
+{
+  "SecurityPki": {
+    "SubjectName": "CN=aio-opc-opcuabroker",
+    "ApplicationUri": "urn:microsoft.com:aio:opc:ua:broker",
+    "SubjectAlternativeDnsNames": "opcua-connector.iot-ops.svc.cluster.local,opcua.contoso.com",
+    "SubjectAlternativeIpAddresses": "192.168.1.100,10.0.0.50"
+  }
+}
+```
+
+The resulting certificate SAN includes the application URI, all specified DNS names and IP addresses, and the local hostname that the connector adds automatically.
+
+### Regenerate the certificate with new SAN entries
+
+If you change the SAN configuration on a running connector, regenerate the certificate to apply the new entries:
+
+1. Update the configuration with the new SAN values.
+1. Delete the existing certificate from the PKI store:
+
+   ```bash
+   rm -rf -- /tmp/opcuabroker/pki/own/certs/* /tmp/opcuabroker/pki/own/private/*
+   ```
+
+1. Restart the connector pod. The connector automatically generates a new certificate with the updated SAN entries.
+
+To verify the new certificate contains the expected SAN entries, run the following command:
+
+```bash
+openssl x509 -in /tmp/opcuabroker/pki/own/certs/your-cert-file.der -inform DER -text -noout | grep -A 10 "Subject Alternative Name"
+```
+
+### Troubleshoot SAN validation failures
+
+If an OPC UA server rejects connections with certificate hostname or IP validation errors:
+
+1. Check the server's error message for the hostname or IP address it validated against.
+1. Add that hostname or IP address to the appropriate SAN configuration property (`SubjectAlternativeDnsNames` or `SubjectAlternativeIpAddresses`).
+1. Regenerate the certificate as described in the previous section.

articles/iot-operations/discover-manage-assets/howto-configure-opc-ua.md

@@ -435,7 +435,7 @@ Now you can define the events associated with the event group. To add OPC UA eve
 
 # [Azure CLI](#tab/cli)
 
-To add an event group and events to an existing asset, use the `az iot ops ns asset opcua event-group` and `az iot ops ns asset custom event` commands:
+To add an event group and events to an existing asset, use the `az iot ops ns asset opcua event-group` and `az iot ops ns asset opcua event` commands:
 
 ```azurecli
 # Add an event group to the thermostat asset
@@ -444,17 +444,17 @@ az iot ops ns asset opcua event-group add \
   --asset thermostat \
   --instance {your instance name} \
   -g {your resource group name} \
-  --name alerts
+  --name alerts \
+  --dest topic="azure-iot-operations/events/test-thermostat-cli" retain=Never qos=Qos1 ttl=3600
 
 # Add an event to the event group
-az iot ops ns asset custom event add \
+az iot ops ns asset opcua event add \
   --asset thermostat \
   --instance {your instance name} \
   -g {your resource group name} \
   --event-group alerts \
   --name serverObjectNotifier \
-  --data-source "ns=0;i=2253" \
-  --dest topic="azure-iot-operations/events/test-thermostat-cli" retain=Never qos=Qos1 ttl=3600
+  --data-source "ns=0;i=2253"
 
 # List the event groups for the asset
 az iot ops ns asset opcua event-group list \
@@ -469,7 +469,7 @@ When you add an event group by using the Azure CLI, you can configure:
 - Publishing interval and queue size
 - Event destinations (MQTT topic, QoS, retain, TTL)
 
-To add individual events to an event group, use the `az iot ops ns asset custom event add` command with the `--event-group` parameter.
+To add individual events to an event group, use the `az iot ops ns asset opcua event add` command with the `--event-group` parameter.
 
 To remove an event group, use the `az iot ops ns asset opcua event-group remove` command.
 
@@ -542,14 +542,13 @@ The following screenshot shows an example event filter:
 The following command updates an existing event definition to include an event filter by using the `config` parameter:
 
 ```azurecli
-az iot ops ns asset custom event add \
+az iot ops ns asset opcua event add \
   --asset thermostat \
   --instance {your instance name} \
   -g {your resource group name} \
   --event-group alerts \
   --name serverObjectNotifier \
   --data-source "ns=0;i=2253" \
-  --dest topic="azure-iot-operations/events/test-thermostat-cli" retain=Never qos=Qos1 ttl=3600 \
   --replace true \
   --config "{\"eventFilter\":{\"selectClauses\":[{\"browsePath\":\"EventId\",\"typeDefinitionId\":\"ns=0;i=2041\",\"fieldId\":\"myEventId\"},{\"browsePath\":\"EventType\",\"typeDefinitionId\":\"ns=0;i=2041\",\"fieldId\":\"EventType\"},{\"browsePath\":\"SourceName\",\"typeDefinitionId\":\"\",\"fieldId\":\"mySourceName\"},{\"browsePath\":\"Severity\",\"typeDefinitionId\":\"\",\"fieldId\":\"Severity\"}]}}"
 ```
@@ -875,6 +874,72 @@ To delete individual resources by using Bicep, see [Deployment stacks](/azure/az
 
 ---
 
+
+## Configure a shared endpoint
+
+By default, each asset opens its own dedicated OPC UA session. You can configure a *shared* endpoint so that the connector uses a single session for all assets that reference the endpoint. To learn more about shared endpoints and when to use them, see [Shared endpoint mode](overview-opc-ua-connector.md#shared-endpoint-mode).
+
+To enable shared mode, set `"shared": true` in the `additionalConfiguration` JSON of a device inbound endpoint:
+
+```json
+{
+  "properties": {
+    "endpoints": {
+      "inbound": {
+        "my-opcua-endpoint": {
+          "address": "opc.tcp://my-plc.my-namespace:4840",
+          "endpointType": "Microsoft.OpcUa",
+          "authentication": {
+            "method": "Anonymous"
+          },
+          "additionalConfiguration": "{\"shared\": true}"
+        }
+      }
+    }
+  }
+}
+```
+
+If you omit the `shared` property from `additionalConfiguration`, the default value is `false` and each asset opens its own dedicated OPC UA session.
+
+The `shared` flag is also supported on legacy `AssetEndpointProfile` resources. However, for new deployments, use the device/asset (namespaced) resource model.
+
+Multiple assets can then reference the same shared endpoint:
+
+```yaml
+apiVersion: namespaces.deviceregistry.microsoft.com/v1
+kind: Asset
+metadata:
+  name: asset-temperature
+  namespace: azure-iot-operations
+spec:
+  deviceRef:
+    deviceName: my-shared-plc
+    endpointName: my-opcua-endpoint
+  datasets:
+    - name: temperature-data
+      dataPoints:
+        - name: temperature
+          dataSource: "ns=2;i=1001"
+---
+apiVersion: namespaces.deviceregistry.microsoft.com/v1
+kind: Asset
+metadata:
+  name: asset-pressure
+  namespace: azure-iot-operations
+spec:
+  deviceRef:
+    deviceName: my-shared-plc
+    endpointName: my-opcua-endpoint
+  datasets:
+    - name: pressure-data
+      dataPoints:
+        - name: pressure
+          dataSource: "ns=2;i=1002"
+```
+
+Both `asset-temperature` and `asset-pressure` reuse the single OPC UA session that the connector established for `my-opcua-endpoint`.
+
 ## Related content
 
 - [Manage asset and device configurations](howto-use-operations-experience.md)

articles/iot-operations/discover-manage-assets/howto-control-opc-ua.md

@@ -376,7 +376,7 @@ The response to a successfully executed request is a message that contains all t
 
 Endpoint operations are process control calls that work on an inbound endpoint only. They don't need an asset.
 
-For example, to dump the address space of an OPC UA server, send a message to the topic `azure-iot-operations/endpoint-operations/{InboundEndpointName}/browse`.
+For example, to dump the address space of an OPC UA server, send a message to the topic `azure-iot-operations/endpoint-operations/{DeviceName}/{EndpointName}/{ActionName}`.
 
 If the payload contains an empty JSON object, the entire address space is returned.
 

articles/iot-operations/discover-manage-assets/overview-opc-ua-connector-certificates-management.md

@@ -28,7 +28,8 @@ The following diagram shows the sequence of events that occur when the connector
 
 :::image type="content" source="media/overview-opc-ua-connector-certificates-management/mutual-trust.svg" alt-text="Diagram that summarizes the OPC UA connector connection handshake." border="false":::
 
-<!-- ```mermaid
+<!--
+mermaid
 sequenceDiagram
     participant Connector as Connector for OPC UA
     participant OPCUA as OPC UA server
@@ -40,7 +41,7 @@ sequenceDiagram
     OPCUA->>Connector: Presents OPC UA server application instance certificate
 
     Connector->>Connector: Validate OPC UA server certificate against<br>connector for OPC UA trusted certificates list<br>or trusted issuers list.
-``` -->
+-->
 
 ## Connector for OPC UA application instance certificate
 
@@ -89,6 +90,42 @@ The default name for the `SecretProviderClass` custom resource that handles the
 
 To learn how to manage the issuer certificates list, see [Configure the issuer certificates list](howto-configure-opc-ua-certificates-infrastructure.md#configure-the-issuer-certificates-list).
 
+## Certificate subject alternative name
+
+Subject Alternative Name (SAN) is an X.509 certificate extension that specifies additional identities for a certificate beyond the subject field. For OPC UA certificates, the SAN typically includes:
+
+- **URI entries**: The OPC UA application URI, required by the OPC UA specification.
+- **DNS entries**: Hostnames and FQDNs where the application can be reached.
+- **IP entries**: IP addresses where the application can be reached.
+
+The connector's self-signed certificate automatically includes the application URI and the local hostname. OPC UA servers validate that the client's certificate SAN contains the hostname or IP address used for the connection. If the SAN doesn't match, the server rejects the connection.
+
+### When to configure custom SAN entries
+
+Configure custom SAN entries when:
+
+- The connector is accessed through multiple hostnames, for example `opcua.local` and `broker.contoso.com`.
+- The connector has multiple IP addresses across different network interfaces.
+- You use Kubernetes services or ingress that expose different DNS names.
+- You connect through a load balancer or proxy.
+- OPC UA servers reject connections because of a hostname or IP mismatch.
+
+### SAN configuration properties
+
+Add the following properties to the `SecurityPki` configuration section:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `SubjectAlternativeDnsNames` | string | Comma-separated list of DNS names to include in the certificate SAN. |
+| `SubjectAlternativeIpAddresses` | string | Comma-separated list of IP addresses to include in the certificate SAN. |
+
+DNS names can be hostnames, FQDNs, or Kubernetes service names and are case-insensitive. IP addresses must be valid IPv4 or IPv6 addresses. The connector automatically trims whitespace and removes empty entries.
+
+> [!IMPORTANT]
+> Custom SAN entries only apply to self-generated certificates. If you provide a custom certificate through the `ApplicationCert` secret or specify an existing certificate through `Thumbprint`, the certificate already exists and its SAN can't be modified. Wildcard DNS names aren't supported in OPC UA certificates.
+
+To learn how to configure custom SAN entries and regenerate the connector certificate, see [Configure certificate subject alternative names](howto-configure-opc-ua-certificates-infrastructure.md#configure-certificate-subject-alternative-names).
+
 ## Features supported
 
 The following table shows the feature support level for authentication in the current version of the connector for OPC UA:

articles/iot-operations/discover-manage-assets/overview-opc-ua-connector.md

@@ -55,6 +55,7 @@ The connector for OPC UA supports the following features as part of Azure IoT Op
 | Payload compression | Yes | Supports `gzip` and `brotli` |
 | [Dynamic node resolution](#resolve-nodes-dynamically-by-using-browse-paths) | Yes | Using `TranslateBrowsePathToNodeId` service |
 | State store synchronization | Yes | Sync OPC UA node properties to distributed state store |
+| [Shared endpoint mode](#shared-endpoint-mode) | Yes | Multiple assets share a single OPC UA session |
 | [Key frame generation](#understand-key-frames-for-opc-ua-data-points) | Yes | Enables downstream services to recover state more quickly |
 
 ## How it works
@@ -97,6 +98,67 @@ To configure this behavior, select **Sync properties into state store** when you
 
 You can also force a synchronization of all properties by making an MQTT RPC call to the `azure-iot-operation/asset-operations/{AssetName}/builtin/syncProperties` topic. A payload `{}` forces a synchronization without observing `ModelChange` events. A payload `{"observeModelChanges": true}` forces a synchronization that observes `ModelChange` events.
 
+## Shared endpoint mode
+
+By default, each asset that connects to an OPC UA server opens its own independent OPC UA session. This default behavior is called *dedicated* mode.
+
+When you set the `shared` flag to `true` on a device's inbound endpoint, the connector establishes a single OPC UA session for the endpoint and reuses it across all assets that reference that endpoint. This behavior is called *shared* mode.
+
+```
+Dedicated mode (default)           Shared mode
+─────────────────────────          ─────────────────────────
+Asset A  →  Session A              Asset A ─┐
+Asset B  →  Session B              Asset B ──┼─→  Session (shared)
+Asset C  →  Session C              Asset C ─┘
+(3 sessions to the server)         (1 session to the server)
+```
+
+### When to use shared mode
+
+Use shared mode when:
+
+- The OPC UA server enforces a low session limit, for example a PLC that allows only a few simultaneous connections.
+- You have many assets pointing to the same server and want to minimize the connection footprint.
+- You want to reduce resource consumption (memory, TCP connections, licensing) on the OPC UA server.
+
+The `shared` flag is independent of the authentication method. The single shared session uses whichever authentication method you configure on the endpoint. Telemetry payload, topic structure, and message schema are identical regardless of session mode.
+
+You can mix shared and dedicated assets on the same device. Create separate endpoints, for example `my-opcua-endpoint-shared` and `my-opcua-endpoint-dedicated`, each with its own `shared` flag. Assets reference a specific endpoint by name through `deviceRef.endpointName`.
+
+### Constraints and trade-offs
+
+| Aspect | Dedicated mode | Shared mode |
+|---|---|---|
+| Sessions to server | One per asset | One per endpoint |
+| Server session limit impact | High | Low |
+| Isolation between assets | Full (each asset has its own session) | None (all assets share the same session) |
+| Session disconnect impact | Only the affected asset reconnects | All assets on the endpoint are affected |
+| Certificate update | Each asset reconnects independently | The single shared session is recreated; all assets on the endpoint are briefly interrupted |
+
+> [!IMPORTANT]
+> When the shared OPC UA session disconnects because of a network failure, server restart, or certificate rotation, all assets that reference the endpoint temporarily lose telemetry until the session is reestablished.
+
+### Shared endpoint lifecycle
+
+1. When you create or update a device resource, the connector reads the `shared` flag.
+1. If `shared` is `true`, the connector opens one OPC UA session before any asset connects. The endpoint transitions to the `Shared` state.
+1. When an asset connects, its `ConnectedAsset` record links to the existing session—no second session opens.
+1. When you remove an asset, the OPC UA session stays open for other assets. Only the removed asset's subscriptions are torn down.
+1. When you delete or update the device, the shared session disconnects and all linked assets are requeued.
+
+If you change `shared` from `true` to `false` on a running device, the connector disconnects the shared session and requeues all affected assets. Each asset then establishes its own dedicated session. Expect a brief interruption in telemetry.
+
+### Health states for shared endpoints
+
+- The **InboundEndpoint** health state reports `Available` or `Unavailable` for the single shared session.
+- Each **Asset** health state also reports `Available` or `Unavailable`. Because all assets share the same session, a session drop marks all linked assets as `Unavailable` simultaneously.
+
+### Certificate rotation for shared endpoints
+
+When the connector's application certificate is renewed, it recreates the secure channel of the shared session once. All assets on the endpoint are briefly interrupted, then automatically recover without requiring individual reconnects.
+
+To learn how to configure a shared endpoint, see [Configure a shared endpoint](howto-configure-opc-ua.md#configure-a-shared-endpoint).
+
 ## Connector for OPC UA message format
 
 The connector for OPC UA publishes messages from OPC UA servers to the MQTT broker as JSON. Each message has a payload and a collection of properties that are part of the MQTT user properties section. The payload contains the messages from the OPC UA server, and the properties provide metadata.