Manage certificates for external communications

Azure IoT Operations uses TLS to encrypt all communication. This article describes how to manage certificates for external communications, such as authenticating external OPC UA servers.

For information about managing certificates for internal communications, including the default self-signed issuer and bringing your own CA issuer, see Bring your own issuer.

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.

Manage certificates for external communications

Azure IoT Operations uses Azure Key Vault as the managed vault solution on the cloud, and uses Azure Key Vault secret store extension for Kubernetes to sync the secrets down from the cloud and store them on the edge as Kubernetes secrets.

Important

Although Azure IoT Operations uses certificates to secure external communications, these certificates are stored as secrets in Azure Key Vault. When you add a certificate to Azure Key Vault, make sure to add it as a secret, not as a certificate resource.

Configure Azure Key Vault permissions

To use the operations experience to create secrets in the key vault, the user requires Key Vault Secrets Officer permissions at the resource level in Azure.

In a test or development environment, use the following steps to assign the Key Vault Secrets Officer role to your user at the resource group level where the Azure IoT Operations instance and Azure Key Vault instance are deployed:

1. To find the name of the resource group, go to the operations experience web UI, go to the Instances page and find your Azure IoT Operations instance. The resource group name is shown in the Resource group field.

2. Go to the Azure portal and then go to the resource group where your Azure IoT Operations instance and Azure Key Vault instance are deployed.

   Tip

   Use the search box at the top of the Azure portal to quickly find the resource group by typing in the name.

3. Select Access control (IAM) from the left-hand menu. Then select + Add > Add role assignment.

4. On the Role tab, select Key Vault Secrets Officer from the list of roles, and then select Next.

5. On the Members tab, select User, group, or service principal, select Select members, select the user you want to assign the Key Vault Secrets Officer role to, and then select Next.

6. Select Review + assign to complete the role assignment.

In a production environment, follow best practices to secure the Azure Key Vault you use with Azure IoT Operations. For more information, see Best practices for using Azure Key Vault.

Add and use certificates

Connectors use the certificate management experience to configure application authentication to external servers. For example, the connector for OPC UA uses certificates in the trust list to authenticate the server identity of the OPC UA servers it connects to.

When you deploy Azure IoT Operations with secure settings, you can start adding certificates to Azure Key Vault, and sync them to the Kubernetes cluster to be used in the Trust list and Issuer list stores for external connections. Each connector has its own trust list to store the certificates of the external servers it trusts and connects to.

You can manage certificates for external communications using either the operations experience web UI or the Azure CLI:

Operations experience

To manage certificates for external communications, follow these steps:

1. Go to Azure IoT Operations experience, and choose your site and Azure IoT Operations instance.

2. In the left navigation pane, select Devices.

3. Select on Manage certificates and secrets.

   

4. In the Certificates and Secrets page, select on Add new certificate.

   

5. You can add a new certificate in two ways:

   • Upload Certificate: Uploads a certificate to add as a secret to Azure Key Vault and automatically synchronize to the cluster using secret store extension.

     • View the certificate details once uploaded, to ensure you have the correct certificate before adding to Azure Key Vault and synchronizing to the cluster.
     • Use an intuitive name so that you can recognize which secret represents your secret in the future.
     • Select the appropriate certificate store for the connector that uses the certificate. For example, OPC UA trust list.

     

     Note

     Simply uploading the certificate doesn't add the secret to Azure Key Vault and synchronize to the cluster, you must select Apply for the changes to be applied.

   • Add from Azure Key Vault: Add an existing secret from the Azure Key vault to be synchronized to the cluster.

     

     Note

     Make sure to select the secret that holds the certificate you would like to synchronize to the cluster. Selecting a secret that isn't the correct certificate causes the connection to fail.

6. Using the list view you can manage the synchronized certificates. You can view all the synchronized certificates, and which certificate store it's synchronized to:

   

You can delete synced certificates as well. When you delete a synced certificate, it only deletes the synced certificate from the Kubernetes cluster, and doesn't delete the contained secret reference from Azure Key Vault. You must delete the certificate secret manually from the key vault.

Azure CLI

You can use the Azure CLI to manage the certificates in a connector's trust list. The CLI flow assumes the certificate is already stored as a secret in Azure Key Vault. See Add certificates as secrets to Azure Key Vault for details.

Tip

The Azure CLI flow partially overlaps with the operations experience. The operations experience can also upload a new certificate to Azure Key Vault as part of the same flow, whereas the Azure CLI requires the certificate to already exist as a secret in Azure Key Vault.

Connector for OPC UA

For the connector for OPC UA, use the dedicated az iot ops connector opcua trust and az iot ops connector opcua issuer commands to add certificates to the trust and issuer lists. For more information, see az iot ops connector opcua trust and az iot ops connector opcua issuer.

Other connectors

For the connectors for HTTP/REST, MQTT, ONVIF, SSE, and the media connector, use the following steps to add a certificate to the connector's trust list:

1. Make sure your certificate is already stored as a secret in Azure Key Vault. To learn more, see Add certificates as secrets to Azure Key Vault.

2. Create a synced secret on the cluster that references the Key Vault secret. The following example creates a synced secret named my-trust-list that maps the Azure Key Vault secret my-cert-pem to the file ca.crt on the cluster:

   az iot ops secretsync secret set \
     --instance <your-instance-name> \
     --resource-group <your-resource-group> \
     --name my-trust-list \
     --secret target=ca.crt source=my-cert-pem
   

   For more information, see az iot ops secretsync secret set.

3. Update the connector template to reference the synced secret in the trust-list field of its runtime configuration. Use az iot ops connector template update with the --trust-settings-secret-ref parameter to set the synced secret name. For more information, see az iot ops connector template update.

Add certificates as secrets to Azure Key Vault

If you use the operations experience to select existing certificates that were previously added to Azure Key Vault, make sure that the secrets are in a format and encoding that's supported by Azure IoT Operations.

To add a PEM certificate secret to Azure Key Vault, you can use a command like the following example:

az keyvault secret set \
  --vault-name <your-key-vault-name> \
  --name my-cert-pem \
  --file ./my-cert.pem \
  --encoding hex \
  --content-type 'application/x-pem-file'

To add a binary DER certificate secret to Azure Key Vault, you can use a command like the following example:

az keyvault secret set \
  --vault-name <your-key-vault-name> \
  --name my-cert-der \
  --file ./my-cert.der \
  --encoding hex \
  --content-type 'application/pkix-cert'