Manage Azure IoT Certificates

​

Introduction

When an Azure IoT Edge gateway acts as a transparent gateway for downstream IoT devices or edge modules, the IoT Edge hub (EdgeHub) requires a server certificate to establish TLS connections with those clients. This server certificate is signed by a Device CA certificate. Edge Infrastructure Services manages the certificate lifecycle for Azure IoT projects:

• You upload a root or intermediate CA certificate (the IoT Edge Signing Certificate) at the project level.
• Edge Infrastructure Services generates a Device CA certificate for each node in the project, signed by the IoT Edge Signing Certificate.
• The Device CA certificate and its key are delivered to the node through EVE-OS (Edge Virtualization Engine) using the cloud-init mechanism.
• Edge Infrastructure Services monitors certificate expiry and alerts you when action is required.

This certificate management is only needed when IoT Edge acts as a transparent gateway. If your deployment does not use downstream leaf devices or edge modules that connect through the gateway, you do not need to attach a certificate. For more information on how Azure IoT certificates work, see the Azure IoT Edge certificate documentation.

​

Prerequisites

• You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
• An Azure IoT project exists. See Create an Azure IoT Project.
• You have a root or intermediate CA certificate and its private key.

​

Upload an IoT Edge Signing Certificate

You attach the signing certificate during project creation or when editing an existing project. During project creation:

1. In the project creation wizard, after completing the Azure resource configuration, enable the Attach certificate for Edge hub TLS (downstream devices and modules) toggle.
2. Upload the root or intermediate CA certificate file.
3. Upload the corresponding private key file.
4. If the key is password-protected, enter the key password.
5. Continue through the wizard and click Create Project.

On an existing project:

1. In the sidebar, go to Infrastructure > Fleet > Projects and click the project name.
2. Click the Configure (gear) icon to open the edit dialog.
3. Locate the certificate section and upload the new certificate and private key.
4. Click Save.

After uploading, the project detail page shows the certificate’s validity dates, issuer details, serial number, and signature algorithm.

​

Device CA Certificate Generation

When you deploy an Azure IoT Edge runtime application instance to a node in the project, Edge Infrastructure Services can automatically generate a Device CA certificate for that node. The Device CA certificate is signed by the IoT Edge Signing Certificate you uploaded. To enable Device CA certificate generation, include the following system variables in the application instance’s custom configuration: For instructions on using system variables in application custom configuration, see Custom Configuration for Applications. Edge Infrastructure Services packages the generated Device CA certificate, the Device CA key, and the public part of the IoT Edge Signing Certificate into the cloud-init payload and delivers them to EVE-OS, which passes them to the application runtime. The application instance detail page shows the current Device CA certificate in use.

​

Renew a Certificate

The following scenarios trigger certificate renewal.

​

The IoT Edge Signing Certificate is about to expire

Edge Infrastructure Services monitors the IoT Edge Signing Certificate and triggers a renewal process 30 days before expiry:

1. A notification appears on the project detail page indicating that the certificate is expiring.
2. Click Update Certificate on the project detail page to initiate renewal.
3. Edge Infrastructure Services generates a new signing certificate and updates all application instances in the project.

​

The Device CA certificate has expired

When a Device CA certificate expires:

1. The project detail page shows a notification: “The CA certificate has expired”.
2. All application instances deployed through the project’s application policy show an error in their detail page.
3. Renew the IoT Edge Signing Certificate as described in the preceding section, or upload a new one, to trigger regeneration of Device CA certificates for all affected nodes.

​

The IoT Edge Signing Certificate is compromised

If the IoT Edge Signing Certificate is compromised:

1. Upload a new intermediate CA certificate in the project configuration.
2. Edge Infrastructure Services prompts you to perform a force update of the application instances for the project.
3. After confirming the force update, Edge Infrastructure Services generates new Device CA certificates using the new signing certificate and pushes the updated credentials to EVE-OS, which purges and restarts the application instances.

​

A Device CA certificate is compromised

If an individual Device CA certificate is compromised:

1. Open the affected application instance’s detail page.
2. From the actions menu, click Purge and Refresh.
3. Edge Infrastructure Services regenerates the Device CA certificate and pushes the new credentials to the node.

Upon every Purge and Refresh or force update, Edge Infrastructure Services performs the following actions in order: fetches updated app details, regenerates the cloud-init payload (including a new Device CA certificate), and issues the purge operation for purgeable volumes.

​

Next Steps