Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
In this article, you learn how to configure the OPC UA certificates infrastructure for the connector for OPC UA. This configuration lets you determine which OPC UA servers you trust to securely establish a session with.
Based on the OPC UA specification, the connector for OPC UA acts as a single OPC UA application when it establishes secure communications with OPC UA servers. The connector for OPC UA uses the same application instance certificate for all secure channels it opens to your OPC UA servers.
The connector for OPC UA must trust the OPC UA servers it connects to. The connector maintains a list of trusted certificates. To learn more, see:
- Manage certificates for your Azure IoT Operations deployment - this article describes how Azure IoT Operations uses Azure Key Vault to manage certificates.
- OPC UA certificates infrastructure for the connector for OPC UA - this article describes the roles of the trusted certificates list and issuer certificates list.
Prerequisites
- An Azure IoT Operations instance deployed with secure settings. To deploy Azure IoT Operations with secure settings, follow the steps in Deploy Azure IoT Operations to a production cluster. If you previously deployed Azure IoT Operations with test settings, you need to first enable secure settings.
The Azure CLI version 2.62.0 or newer installed on your development machine. Use
az --versionto check your version andaz upgradeto update if necessary. For more information, see Install the Azure CLI.The Azure IoT Operations extension for the Azure CLI. Use the following command to add the extension or update it to the latest version:
az extension add --upgrade --name azure-iot-ops
- The connector for OPC UA is enabled on your Azure IoT Operations instance.
Configure a self-signed application instance certificate for the connector for OPC UA
The default deployment of the connector for OPC UA installs all the resources needed by cert-manager to create an OPC UA compliant self-signed certificate. This certificate is stored in the aio-opc-opcuabroker-default-application-cert secret. This secret is mapped into all the connector for OPC UA pods and acts as the OPC UA client application instance certificate. cert-manager handles the automatic renewal of this application instance certificate.
This configuration is typically sufficient for compliant and secure communication between your OPC UA servers and the connector for OPC UA in a demonstration or exploration environment. For a production environment, use enterprise-grade application instance certificates in your deployment.
Configure a custom self-signed application instance certificate
If you need more control over the application instance certificate than cert-manager provides, you can generate a custom self-signed certificate by using OpenSSL and register it with the connector for OPC UA. This approach is useful in test or QA environments where you need to match specific OPC UA server requirements.
Generate the certificate
Use the following openssl command to generate a self-signed X.509 certificate with an RSA 2048-bit key pair, valid for 365 days:
openssl req -x509 -newkey rsa:2048 \
-keyout opcuabroker-custom-own.pem \
-out opcuabroker-custom-own.der \
-outform DER \
-sha256 -days 365 -noenc \
-subj "/CN=aio-opc-opcuabroker-custom" \
-addext "subjectAltName=URI:urn:microsoft.com:aio:opc:opcuabroker:custom" \
-addext "keyUsage=critical, nonRepudiation, digitalSignature, keyEncipherment, dataEncipherment, keyCertSign" \
-addext "extendedKeyUsage=critical, serverAuth, clientAuth" \
-addext "basicConstraints=CA:FALSE"
This command generates the certificate in DER format (opcuabroker-custom-own.der) and the private key in PEM format (opcuabroker-custom-own.pem). The certificate includes the OPC UA application URI as a Subject Alternative Name and the appropriate key usage extensions for server and client authentication.
Register the certificate with the connector
Use the following command to upload the generated certificate and private key to the OPC UA connector instance:
az iot ops connector opcua client add \
--instance <your instance name> \
-g <your resource group> \
--public-key-file "./opcuabroker-custom-own.der" \
--private-key-file "./opcuabroker-custom-own.pem" \
--subject-name "aio-opc-opcuabroker-custom" \
--application-uri "urn:microsoft.com:aio:opc:opcuabroker:custom"
Important
The --subject-name and --application-uri values must exactly match the corresponding values in the certificate. Specifically, the subject name must match the Common Name (CN) from the -subj parameter and the application URI must match the URI from the subjectAltName extension. A mismatch causes the OPC UA session establishment to fail because the OPC UA server validates that the application instance certificate matches the client's declared identity.
After you register the custom certificate, don't forget to add the new certificate's public key to the trusted certificate lists of all OPC UA servers the connector needs to connect to. For more information, see Configure your OPC UA server.
Configure the trusted certificates list
To connect to an OPC UA server, first you need to establish the application authentication mutual trust. To configure the trusted certificates list of the servers you want the connector for OPC UA to connect to:
To use the operations experience web UI to manage the trusted certificates list, complete the following steps:
Get the OPC UA server application's instance certificate as a file. These files typically have a
.deror.crtextension. This file contains the public key only.Tip
Typically, an OPC UA server has an interface that lets you export its application instance certificate. This interface isn't standardized. For servers such as KEPServerEx, there's a Windows-based configuration UI for certificates management. Other servers might have a web interface or use operating system folders to store the certificates. To find out how to export the application instance certificate, refer to the user manual of your server. After you have the certificate, make sure it's either DER or PEM encoded. These certificates are typically stored in files with either the
.deror.crtextension. If the certificate isn't in one of those file formats, use a tool such asopensslto transform the certificate into the required format.You can add the certificate directly to your Azure Key Vault as a secret and import from there, or you can upload the certificate to the trusted certificates list using the operations experience.
Note
The connector for OPC UA uses a Kubernetes-native secret named
aio-opc-ua-broker-trust-listto store the trusted certificates list. This secret is created when you deploy Azure IoT Operations.Go to the Devices page in the operations experience web UI.
To view the trusted certificates list, select Manage certificates and secrets and then Certificates:
You can upload a certificate file from your local machine or add one that you previously added as a secret in your Azure Key Vault:
Select Apply to save the changes. The certificate is now added to the trusted certificates list. If you upload the certificate, it's automatically added to your Azure Key Vault as a secret.
If your OPC UA server uses a certificate issued by a certificate authority (CA), you can trust the CA by adding its public key certificate to the trusted certificates list. The connector for OPC UA now automatically trusts all the servers that use a valid certificate issued by the CA. Therefore, you don't need to explicitly add the OPC UA server's certificate to the connector for OPC UA's trusted certificates list. Currently, you can't use the operations experience to add a certificate revocation list to the trusted certificates list.
Tip
To add a new certificate in the operations experience, you must be assigned to the Key Vault Secrets Officer role for your Azure Key Vault.
Important
If you're adding a certificate from Azure Key Vault, it must be stored as a secret and not as a certificate.
Configure the issuer certificates list
If your OPC UA server uses a certificate issued by a CA, but you don't want to trust all certificates issued by the CA, configure the issuer certificates list:
Before you can configure the issuer certificates list with your intermediate certificates, you need to add the CA certificate to the trusted certificates list. The connector for OPC UA uses the CA certificate to validate the issuer chain of the OPC UA server's certificate.
To use the operations experience web UI to manage the issuer certificates list, complete the following steps:
Get the issuer certificate that was used to sign your server instance certificates as a file. These files typically have a
.deror.crtextension. This file contains the public key only. You might also have a .crl file (certificate revocation list) for the issuer certificate.You can add the issuer certificate directly to your Azure Key Vault as a secret and import from there, or you can upload the certificate and certificate revocation list (.crl file) to the issuer certificates list using the operations experience.
Note
The connector for OPC UA uses a Kubernetes-native secret named
aio-opc-ua-broker-issuer-listto store the issuer certificates list. This secret is created when you deploy Azure IoT Operations.Go to the Devices page in the operations experience web UI.
To view the issuer certificates list, select Manage certificates and secrets and then Certificates. The filter box lets you view the different certificate lists:
You can upload an issuer certificate file from your local machine or add one that you previously added as a secret in your Azure Key Vault:
Select Apply to save the changes. The certificate is now added to the issuer certificates list. If you upload the certificate, it's automatically added to your Azure Key Vault as a secret.
You can also use the operations experience to add a certificate revocation list (.crl file) to the issuer certificates list.
Tip
To add a new certificate in the operations experience, you must be assigned to the Key Vault Secrets Officer role for your Azure Key Vault.
Important
If you're adding a certificate from Azure Key Vault, it must be stored as a secret and not as a certificate.
Configure your OPC UA server
To complete the configuration of the application authentication mutual trust, you need to configure your OPC UA server to trust the connector for OPC UA application instance certificate:
To extract the connector for OPC UA certificate into a
opcuabroker.crtfile, run the following command:kubectl -n azure-iot-operations get secret aio-opc-opcuabroker-default-application-cert -o jsonpath='{.data.tls\.crt}' | base64 -d > opcuabroker.crtkubectl -n azure-iot-operations get secret aio-opc-opcuabroker-default-application-cert -o jsonpath='{.data.tls\.crt}' | %{ [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($_)) } > opcuabroker.crtMany OPC UA servers only support certificates in the DER format. If necessary, use the following command to convert the
opcuabroker.crtcertificate toopcuabroker.der:openssl x509 -outform der -in opcuabroker.crt -out opcuabroker.derConsult the documentation of your OPC UA server to learn how to add the
opcuabroker.crtoropcuabroker.dercertificate file to the server's trusted certificates list.
Configure an enterprise-grade application instance certificate
For production environments, you can configure the connector for OPC UA to use an enterprise-grade application instance certificate. Typically, an enterprise CA issues this certificate and you need to add the CA certificate to your configuration. Often, there's a hierarchy of CAs and you need to add the complete validation chain of CAs to your configuration.
The following example references the following items:
| Item | Description |
|---|---|
opcuabroker-certificate.der |
File that contains the enterprise-grade application instance certificate public key. |
opcuabroker-certificate.pem |
File that contains the enterprise-grade application instance certificate private key. |
subjectName |
The subject name string embedded in the application instance certificate. |
applicationUri |
The application instance URI embedded in the application instance. |
enterprise-grade-ca-1.der |
File that contains the enterprise-grade CA certificate public key. |
enterprise-grade-ca-1.crl |
The CA's CRL file. |
Like the previous examples, you use a dedicated Kubernetes secret to store the certificates and CRLs. To configure the enterprise-grade application instance certificate, complete the following steps:
Save the certificates and the CRL in the
aio-opc-ua-broker-client-certificatesecret by using the following command:# Create aio-opc-ua-broker-client-certificate secret # Upload OPC UA public key certificate as an entry to the secret # Upload OPC UA private key certificate as an entry to the secret az iot ops connector opcua client add \ --instance <your instance name> \ -g <your resource group> \ --public-key-file "./opcuabroker-certificate.der" \ --private-key-file "./opcuabroker-certificate.pem" \ --subject-name <subject name from the public key cert> \ --application-uri <application uri from the public key cert>Important
The
--subject-nameand--application-urivalues must exactly match the corresponding values in the certificate. A mismatch causes the OPC UA session establishment to fail, as the OPC UA server validates that the application instance certificate matches the client's declared identity.If you use the CA to issue certificates for your connector for OPC UA, configure the
aio-opc-ua-broker-issuer-listsecret. Use a Kubernetes client such askubectlto configure the secretsenterprise-grade-ca-1.derandenterprise-grade-ca-1.crl:# Append CA certificate to the issuer list secret as a new entry az iot ops connector opcua issuer add --instance <your instance name> --resource-group <your resource group> --certificate-file "./enterprise-grade-ca-1.der" # Append the CRL to the issuer list secret as a new entry az iot ops connector opcua issuer add --instance <your instance name> --resource-group <your resource group> --certificate-file "./enterprise-grade-ca-1.crl"
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.
Relax the certificate validation on your OPC UA connector (optional)
Caution
Only use the following settings in test or QA environments where target OPC UA servers use legacy certificates.
To lower the connector's PKI security restrictions to allow communication with OPC UA servers that use weaker certificates:
az k8s-extension update --name <your instance name> \
--cluster-name <your cluster name> \
--resource-group <your resource group> \
--cluster-type connectedClusters \
--config connectors.values.securityPki.minimumCertificateKeySize=1024 \
--config connectors.values.securityPki.rejectSha1SignedCertificates=false
The following table describes these settings:
| Setting | Default | Description |
|---|---|---|
connectors.values.securityPki.minimumCertificateKeySize |
2048 |
The minimum RSA key size, in bits, that the connector accepts for server certificates. |
connectors.values.securityPki.rejectSha1SignedCertificates |
true |
Whether the connector rejects server certificates signed with the deprecated SHA-1 algorithm. |
Reset PKI security settings to defaults
Configuration overrides applied by az k8s-extension update --config are sticky. Once you set them, they persist across updates. To restore the default security settings, explicitly set them back:
az k8s-extension update --name <your instance name> \
--cluster-name <your cluster name> \
--resource-group <your resource group> \
--cluster-type connectedClusters \
--config connectors.values.securityPki.minimumCertificateKeySize=2048 \
--config connectors.values.securityPki.rejectSha1SignedCertificates=true
Verify connector configuration after certificate changes
After you update certificates or PKI security settings, verify that the connector pods pick up the new configuration. Run the following command to check the status of the connector pods:
kubectl get pods -n azure-iot-operations | grep -E "aio-opc-opc.tcp|aio-opc-opcua-commander"
To force the pods to reload the updated certificate and security settings, restart them:
kubectl delete pod -n azure-iot-operations $(kubectl get pods -n azure-iot-operations -o name | grep "aio-opc-opc.tcp")
kubectl delete pod -n azure-iot-operations $(kubectl get pods -n azure-iot-operations -o name | grep "aio-opc-opcua-commander")
The pods are automatically recreated by their respective deployments. Verify they come back up in a Running state before you proceed with OPC UA connectivity tests.
Note
You only need to restart pods if the connector doesn't automatically pick up the new configuration. In most cases, the connector detects certificate changes and reloads them automatically.
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.
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.
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:
{
"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:
Update the configuration with the new SAN values.
Delete the existing certificate from the PKI store:
rm -rf -- /tmp/opcuabroker/pki/own/certs/* /tmp/opcuabroker/pki/own/private/*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:
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:
- Check the server's error message for the hostname or IP address it validated against.
- Add that hostname or IP address to the appropriate SAN configuration property (
SubjectAlternativeDnsNamesorSubjectAlternativeIpAddresses). - Regenerate the certificate as described in the previous section.
SecurityPki configuration reference
Configure securityPki settings by using az k8s-extension update:
az k8s-extension update --name <your instance name> \
--cluster-name <your cluster name> \
--resource-group <your resource group> \
--cluster-type connectedClusters \
--config connectors.values.securityPki.<settingName>=<value>
az k8s-extension update --name <your instance name> `
--cluster-name <your cluster name> `
--resource-group <your resource group> `
--cluster-type connectedClusters `
--config connectors.values.securityPki.<settingName>=<value>
Certificate validation settings
| Setting | Type | Default | Description |
|---|---|---|---|
minimumCertificateKeySize |
int | 2048 |
Minimum RSA key size to accept. Supported values: 1024 (deprecated), 2048, 3072, 4096. |
rejectSha1SignedCertificates |
bool | true |
Whether to reject peer certificates signed with the deprecated SHA-1 algorithm. |
rejectUnknownRevocationStatus |
bool | false |
Whether to reject CA certificates whose revocation status cannot be verified (for example, CRL not available). Should be false when deployDefaultIssuerCA is used. |
suppressNonceValidationErrors |
bool | false |
Suppresses errors caused by non-conformant clients or servers that may repeat nonce or use nonce with insufficient entropy. Only use in test/QA environments. |
Certificate chain and trust settings
| Setting | Type | Default | Description |
|---|---|---|---|
sendCertificateChain |
bool | true |
Whether to send the full certificate chain for CA-signed application instance certificates during authentication with a server. |
trustOwnCertIssuer |
bool | true |
Whether to trust the issuer CA when provided in the own certificate store. |
deployDefaultIssuerCA |
bool | false |
Whether to deploy a default issuer CA for the connector for OPC UA to use to sign application instance certificates. When enabled, automatically creates a self-signed root CA and issuer certificates. |
Application instance certificate identity
| Setting | Type | Default | Description |
|---|---|---|---|
subjectName |
string | "aio-opc-opcuabroker" |
Subject of the application instance certificate. Must match the certificate's Common Name. |
applicationUri |
string | "urn:microsoft.com:aio:opc:ua:broker" |
The URI of the application instance certificate. Must match the certificate's Subject Alternative Name URI. |