Configure OPC UA certificates infrastructure for the connector for OPC UA
Important
Azure IoT Operations Preview – enabled by Azure Arc is currently in preview. You shouldn't use this preview software in production environments.
You'll need to deploy a new Azure IoT Operations installation when a generally available release is made available. You won't be able to upgrade a preview installation.
See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
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.
To learn more, see OPC UA certificates infrastructure for the connector for OPC UA.
Prerequisites
A deployed instance of Azure IoT Operations Preview. To deploy Azure IoT Operations for demonstration and exploration purposes, see Quickstart: Run Azure IoT Operations Preview in Github Codespaces with K3s.
Configure a self-signed application instance certificate
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 the trusted certificates list
To connect to an asset, first you need to establish the application authentication mutual trust. For the connector for OPC UA, complete the following steps:
Get the OPC UA server application's instance certificate as a file. These files typically have a .der or .crt extension. This is 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. Refer to the user manual of your server to find out how to export the application instance certificate. After you have the certificate, make sure it's either DER or PEM encoded. Typically stored in files with either the .der or .crt extension. If the certificate isn't in one of those file formats, use a tool such as
openssl
to transform the certificate into the required format.Save the OPC UA server's application instance certificate in Azure Key Vault as a secret.
For a DER encoded certificate in a file such as ./my-server.der, run the following command:
# Upload my-server.der OPC UA server's certificate as secret to Azure Key Vault az keyvault secret set \ --name "my-server-der" \ --vault-name <your-azure-key-vault-name> \ --file ./my-server.der \ --encoding hex \ --content-type application/pkix-cert
For a PEM encoded certificate in a file such as ./my-server.crt, run the following command:
# Upload my-server.crt OPC UA server's certificate as secret to Azure Key Vault az keyvault secret set \ --name "my-server-crt" \ --vault-name <your-azure-key-vault-name> \ --file ./my-server.crt \ --encoding hex \ --content-type application/x-pem-file
Configure the
aio-opc-ua-broker-trust-list
custom resource in the cluster. Use a Kubernetes client such askubectl
to configure the secrets, such asmy-server-der
ormy-server-crt
, in theSecretProviderClass
object array in the cluster.The following example shows a complete
SecretProviderClass
custom resource that contains the trusted OPC UA server certificate in a DER encoded file:apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aio-opc-ua-broker-trust-list namespace: azure-iot-operations spec: provider: azure parameters: usePodIdentity: 'false' keyvaultName: <your-azure-key-vault-name> tenantId: <your-azure-tenant-id> objects: | array: - | objectName: my-server-der objectType: secret objectAlias: my-server.der objectEncoding: hex
The following example shows a complete
SecretProviderClass
custom resource that contains the trusted OPC UA server certificate in a PEM encoded file with the .crt extension:apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aio-opc-ua-broker-trust-list namespace: azure-iot-operations spec: provider: azure parameters: usePodIdentity: 'false' keyvaultName: <your-azure-key-vault-name> tenantId: <your-azure-tenant-id> objects: | array: - | objectName: my-server-crt objectType: secret objectAlias: my-server.crt objectEncoding: hex
Note
The time it takes to project Azure Key Vault certificates into the cluster depends on the configured polling interval.
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 connector for OPC UA 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 trusted certificates list.
To trust a CA, complete the following steps:
Get the CA certificate public key encode in DER or PEM format. These certificates are typically stored in files with either the .der or .crt extension. Get the CA's certificate revocation list (CRL). This list is typically in a file with the .crl. Check the documentation for your OPC UA server for details.
Save the CA certificate and the CRL in Azure Key Vault as secrets.
For a DER encoded certificate in a file such as ./my-server-ca.der, run the following commands:
# Upload CA certificate as secret to Azure Key Vault az keyvault secret set \ --name "my-server-ca-der" \ --vault-name <your-azure-key-vault-name> \ --file ./my-server-ca.der \ --encoding hex \ --content-type application/pkix-cert # Upload the CRL as secret to Azure Key Vault az keyvault secret set \ --name "my-server-crl" \ --vault-name <your-azure-key-vault-name> \ --file ./my-server-ca.crl \ --encoding hex \ --content-type application/pkix-crl
For a PEM encoded certificate in a file such as ./my-server-ca.crt, run the following commands:
# Upload CA certificate as secret to Azure Key Vault az keyvault secret set \ --name "my-server-ca-crt" \ --vault-name <your-azure-key-vault-name> \ --file ./my-server-ca.crt \ --encoding hex \ --content-type application/x-pem-file # Upload the CRL as secret to Azure Key Vault az keyvault secret set \ --name "my-server-crl" \ --vault-name <your-azure-key-vault-name> \ --file ./my-server-ca.crl \ --encoding hex \ --content-type application/pkix-crl
Configure the
aio-opc-ua-broker-trust-list
custom resource in the cluster. Use a Kubernetes client such askubectl
to configure the secrets, such asmy-server-ca-der
ormy-server-ca-crt
, in theSecretProviderClass
object array in the cluster.The following example shows a complete
SecretProviderClass
custom resource that contains the trusted OPC UA server certificate in a DER encoded file:apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aio-opc-ua-broker-trust-list namespace: azure-iot-operations spec: provider: azure parameters: usePodIdentity: 'false' keyvaultName: <your-azure-key-vault-name> tenantId: <your-azure-tenant-id> objects: | array: - | objectName: my-server-ca-der objectType: secret objectAlias: my-server-ca.der objectEncoding: hex - | objectName: my-server-ca-crl objectType: secret objectAlias: my-server-ca.crl objectEncoding: hex
The following example shows a complete
SecretProviderClass
custom resource that contains the trusted OPC UA server certificate in a PEM encoded file with the .crt extension:apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aio-opc-ua-broker-trust-list namespace: azure-iot-operations spec: provider: azure parameters: usePodIdentity: 'false' keyvaultName: <your-azure-key-vault-name> tenantId: <your-azure-tenant-id> objects: | array: - | objectName: my-server-ca-crt objectType: secret objectAlias: my-server-ca.crt objectEncoding: hex - | objectName: my-server-ca-crl objectType: secret objectAlias: my-server-ca.crl objectEncoding: hex
Note
The time it takes to project Azure Key Vault certificates into the cluster depends on the configured polling interval.
Configure the issuer certificates list
If your OPC UA server uses a certificate issued by a certificate authority (CA), but you don't want to trust all certificates issued by the CA, complete the following steps:
Trust the OPC UA server's application instance certificate by following the first three steps in the previous section.
Besides the certificate itself, connector for OPC UA needs the CA certificate to properly validate the issuer chain of the OPC UA server's certificate. Add the CA certificate and its certificate revocation list (CRL) to a separate list called
aio-opc-ua-broker-issuer-list
.Save the CA certificate and the CRL in Azure Key Vault as secrets.
For a DER encoded certificate in a file such as ./my-server-ca.der, run the following commands:
# Upload CA certificate as secret to Azure Key Vault az keyvault secret set \ --name "my-server-ca-der" \ --vault-name <your-azure-key-vault-name> \ --file ./my-server-ca.der \ --encoding hex \ --content-type application/pkix-cert # Upload the CRL as secret to Azure Key Vault az keyvault secret set \ --name "my-server-crl" \ --vault-name <your-azure-key-vault-name> \ --file ./my-server-ca.crl \ --encoding hex \ --content-type application/pkix-crl
For a PEM encoded certificate in a file such as ./my-server-ca.crt, run the following commands:
# Upload CA certificate as secret to Azure Key Vault az keyvault secret set \ --name "my-server-ca-crt" \ --vault-name <your-azure-key-vault-name> \ --file ./my-server-ca.crt \ --encoding hex \ --content-type application/x-pem-file # Upload the CRL as secret to Azure Key Vault az keyvault secret set \ --name "my-server-crl" \ --vault-name <your-azure-key-vault-name> \ --file ./my-server-ca.crl \ --encoding hex \ --content-type application/pkix-crl
Configure the
aio-opc-ua-broker-issuer-list
custom resource in the cluster. Use a Kubernetes client such askubectl
to configure the secrets, such asmy-server-ca-der
ormy-server-ca-crt
, in theSecretProviderClass
object array in the cluster.The following example shows a complete
SecretProviderClass
custom resource that contains the trusted OPC UA server certificate in a DER encoded file:apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aio-opc-ua-broker-issuer-list namespace: azure-iot-operations spec: provider: azure parameters: usePodIdentity: 'false' keyvaultName: <your-azure-key-vault-name> tenantId: <your-azure-tenant-id> objects: | array: - | objectName: my-server-ca-der objectType: secret objectAlias: my-server-ca.der objectEncoding: hex - | objectName: my-server-ca-crl objectType: secret objectAlias: my-server-ca.crl objectEncoding: hex
The following example shows a complete
SecretProviderClass
custom resource that contains the trusted OPC UA server certificate in a PEM encoded file with the .crt extension:apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aio-opc-ua-broker-issuer-list namespace: azure-iot-operations spec: provider: azure parameters: usePodIdentity: 'false' keyvaultName: <your-azure-key-vault-name> tenantId: <your-azure-tenant-id> objects: | array: - | objectName: my-server-ca-crt objectType: secret objectAlias: my-server-ca.crt objectEncoding: hex - | objectName: my-server-ca-crl objectType: secret objectAlias: my-server-ca.crl objectEncoding: hex
Note
The time it takes to project Azure Key Vault certificates into the cluster depends on the configured polling interval.
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.crt
file, 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.crt
In PowerShell, you can complete the same task with the following command:
kubectl -n azure-iot-operations get secret aio-opc-opcuabroker-default-application-cert -o jsonpath='{.data.tls\.crt}' | %{ [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($_)) } > opcuabroker.crt
Many OPC UA servers only support certificates in the DER format. If necessary, use the following command to convert the opcuabroker.crt certificate to opcuabroker.der:
openssl x509 -outform der -in opcuabroker.crt -out opcuabroker.der
Consult the documentation of your OPC UA server to learn how to add the
opcuabroker.crt
oropcuabroker.der
certificate 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 certificate authority (CA) issues this certificate and you need 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 certificate revocation list (CRL) file. |
Like the previous examples, you use Azure Key Vault to store the certificates and CRLs. You then configure the SecretProviderClass
custom resources in the connected cluster to project the certificates and CRLs into the connector for OPC UA pods. To configure the enterprise grade application instance certificate, complete the following steps:
Save the certificates and the CRL in Azure Key Vault as secrets by using the following commands:
# Upload the connector for OPC UA public key certificate as secret to Azure Key Vault az keyvault secret set \ --name "opcuabroker-certificate-der" \ --vault-name <your-azure-key-vault-name> \ --file ./opcuabroker-certificate.der \ --encoding hex \ --content-type application/pkix-cert # Upload connector for OPC UA private key certificate as secret to Azure Key Vault az keyvault secret set \ --name "opcuabroker-certificate-pem" \ --vault-name <your-azure-key-vault-name> \ --file ./opcuabroker-certificate.pem \ --encoding hex \ --content-type application/x-pem-file # Upload CA public key certificate as secret to Azure Key Vault az keyvault secret set \ --name "enterprise-grade-ca-1-der" \ --vault-name <your-azure-key-vault-name> \ --file ./enterprise-grade-ca-1.der \ --encoding hex \ --content-type application/pkix-cert # Upload CA certificate revocation list as secret to Azure Key Vault az keyvault secret set \ --name "enterprise-grade-ca-1-crl" \ --vault-name <your-azure-key-vault-name> \ --file ./enterprise-grade-ca-1.crl \ --encoding hex \ --content-type application/pkix-crl
Configure the
aio-opc-ua-broker-client-certificate
custom resource in the cluster. Use a Kubernetes client such askubectl
to configure the secretsopcuabroker-certificate-der
andopcuabroker-certificate-pem
in theSecretProviderClass
object array in the cluster.The following example shows a complete
SecretProviderClass
custom resource after you add the secret configurations:apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aio-opc-ua-broker-client-certificate namespace: azure-iot-operations spec: provider: azure parameters: usePodIdentity: 'false' keyvaultName: <your-azure-key-vault-name> tenantId: <your-azure-tenant-id> objects: | array: - | objectName: opcuabroker-certificate-der objectType: secret objectAlias: opcuabroker-certificate.der objectEncoding: hex - | objectName: opcuabroker-certificate-pem objectType: secret objectAlias: opcuabroker-certificate.pem objectEncoding: hex
If you use the CA to issue certificates for your OPC UA servers, configure
aio-opc-ua-broker-issuer-list
custom resource in the cluster. Use a Kubernetes client such askubectl
to configure the secretsenterprise-grade-ca-1-der
andenterprise-grade-ca-1-crl
in theSecretProviderClass
object array in the cluster.The following example shows a complete
SecretProviderClass
custom resource after you add the secret configurations:apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: aio-opc-ua-broker-issuer-list namespace: azure-iot-operations spec: provider: azure parameters: usePodIdentity: 'false' keyvaultName: <your-azure-key-vault-name> tenantId: <your-azure-tenant-id> objects: | array: - | objectName: enterprise-grade-ca-1-der objectType: secret objectAlias: enterprise-grade-ca-1.der objectEncoding: hex - | objectName: enterprise-grade-ca-1-crl objectType: secret objectAlias: enterprise-grade-ca-1.crl objectEncoding: hex
Update the connector for OPC UA deployment to use the new
SecretProviderClass
source for application instance certificates by using the following command:az k8s-extension update \ --version 0.3.0-preview \ --name opc-ua-broker \ --release-train preview \ --cluster-name <cluster-name> \ --resource-group <azure-resource-group> \ --cluster-type connectedClusters \ --auto-upgrade-minor-version false \ --config securityPki.applicationCert=aio-opc-ua-broker-client-certificate \ --config securityPki.subjectName=<subjectName> \ --config securityPki.applicationUri=<applicationUri>
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.