> ## Documentation Index
> Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL.
> Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other.
> Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking.
> Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify.

# Manage Azure IoT Certificates

> Upload IoT Edge signing certificates, manage device CA certificate lifecycle, and respond to certificate expiry events in Azure IoT projects.

## 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](https://github.com/Azure/iotedge/blob/main/edgelet/doc/est.md#edge-ca-certificate).

### Prerequisites

* You have the SysManager or SysAdmin role in your enterprise. See [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md).
* An Azure IoT project exists. See [Create an Azure IoT Project](https://zededa.mintlify.site/new-ui/infrastructure-services/integrations-and-automation/azure-iot-hub.md).
* 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:

| Variable | Description |
| - | - |
| `$webhook.azure.iotedge.device_cert_required` | Set to `true` to indicate that the IoT Edge runtime expects a Device CA certificate. |
| `$webhook.azure.iotedge.gen_device_cert` | Set to `true` to instruct Edge Infrastructure Services to generate a Device CA certificate signed by the IoT Edge Signing Certificate. |
| `$webhook.azure.iotedge.gen_device_key` | Set to `true` to generate the private key for the Device CA certificate. |

For instructions on using system variables in application custom configuration, see [Custom Configuration for Applications](https://zededa.mintlify.site/new-ui/marketplace/custom-app-configuration.md).

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

> [card] [Manage Azure Module Policies](https://zededa.mintlify.site/new-ui/infrastructure-services/integrations-and-automation/azure-module-policies.md)
>
> View and manage module deployment policies applied to the project from Azure IoT Hub.

> [card] [Deploy an Azure IoT Application](https://zededa.mintlify.site/new-ui/infrastructure-services/integrations-and-automation/azure-iot-app-deployment.md)
>
> Deploy the IoT Edge runtime application to enrolled nodes.

> [card] [Create an Azure IoT Project](https://zededa.mintlify.site/new-ui/infrastructure-services/integrations-and-automation/azure-iot-hub.md)
>
> Configure the project and attach certificates during setup.

> [card] [Custom Configuration for Applications](https://zededa.mintlify.site/new-ui/marketplace/custom-app-configuration.md)
>
> Use system variables to control Device CA certificate generation.