SAN updates

Author: dominicbetts

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/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: