Configure tenant CA certificates for cloud services
Important
This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.
A tenant CA certificate is issued by the Azure Sphere Security Service when a tenant is created. Each tenant CA certificate has a lifetime of two years and the start date and end date are captured in the certificate.
When the device connects to Azure IoT Hub, Azure IoT Central, or a back-end service, the service must be able to verify that the device belongs to your Azure Sphere tenant and that the tenant itself is legitimate. To perform this authentication, the service requires a valid Azure Sphere tenant CA certificate chain that is used to sign certificates that devices receive as part of daily attestation and authentication. For more information, see Certificate use with Azure Sphere.
When a tenant's current CA certificate is close to expiration, a new tenant CA certificate is automatically issued approximately 90 days before the certificate expires.
You must configure the Azure IoT managed services or back-end service to trust both tenant CA certificates. If both certificates are trusted, the service will be able to use the new certificate as soon as it becomes valid, and thus prevent interruption to communications when the Azure Sphere Security Service switches over to using the new tenant CA certificate.
Provide tenant CA certificate to cloud services
The process of configuring a cloud service to trust the tenant CA certificate involves:
- Step 1: List and identify tenant CA certificates
- Step 2: Download tenant CA certificate
- Step 3: Upload tenant CA certificate and generate the verification code
- Step 4: Verify tenant identity
Step 1: List and identify tenant CA certificates
Run azsphere ca-certificate list to get a list of available certificates for the current tenant.
When the current certificate is due for renewal, the Azure Sphere Security Service automatically generates the next certificate, which is displayed along with the current (active) certificate.
In the list of certificates, the status of the current tenant CA certificate is displayed as Active and the status of the other certificates is displayed as Inactive.
The following table provides details of the status for the certificates:
| Status | Description |
|---|---|
| Active | The current tenant CA certificate. |
| Inactive | The status can mean any of the following: New tenant CA certificate: A new tenant CA certificate is issued when the current tenant CA certificate is close to expiration. The status of the new certificate is displayed as inactive for approximately 45 days after it has been issued. Retired certificate: The validity period for the current active certificate and expiring certificate overlap to avoid disruption or loss of connectivity, when the certificates are switched. When the status of the new certificate changes to active, the status of the old certificate changes to inactive. Expired certificate: The status of the certificate that has expired. |
| Revoked | An untrusted certificate. |
Step 2: Download tenant CA certificate
Run azsphere ca-certificate download to download the required certificate as a '.cer' file.
Example to specify index to download a required certificate:
azsphere ca-certificate download --destination ca-cert.cer --index ``<value>`
Example to specify thumbprint to download a required certificate:
azsphere ca-certificate download --destination ca-cert.cer --thumbprint <value>
Note
Make sure that you provide either the --index or --thumbprint to download the required certificate. If index or thumbprint is not provided, the active certificate is downloaded by default.
Step 3: Upload tenant CA certificate and generate verification code
For Azure IoT managed services, upload the tenant CA certificate to Azure IoT Hub
If you are using a back-end service, consult the documentation provided by the service.
Step 4: Verify tenant identity
For Azure IoT managed services, registration is a two-step process. The first step is to upload the new tenant CA certificate in Azure IoT. The uploaded tenant CA certificate must be verified to prove ownership of the Azure Sphere tenant. In the next step, the Azure Sphere Security Service provides a proof-of-possession certificate. Once the proof-of-possession certificate is uploaded to Azure IoT, the certificate registration process is complete. For more information on verifying the tenant CA certificate, see Set up an Azure IoT Hub or Set up Azure IoT Central.
If you are using a back-end service, consult the documentation provided by the service. For more information, see Set up an Azure IoT Hub or Set up an Azure IoT Hub for Azure Sphere with the Device Provisioning Service.
Timeline for tenant CA certificate renewal
When a tenant CA certificate is about to expire, the renewal procedure is automatically initiated by the Azure Sphere Security Service.
The following illustration shows the stages of certificate renewal:
| Callout | Stage |
|---|---|
| 1 | The current tenant CA certificate (Certificate A) is valid for 2 years and is marked as Active. |
| 2 | The renewal process starts approximately 90 days before Certificate A expires. A new tenant CA certificate (Certificate B) is created and marked as Inactive. At this point, Certificate B is available for download, but Certificate A remains as the Active certificate for approximately 45 days. You must take action within the 45-day period so that your devices continue to authenticate to your cloud services correctly. |
| 3 | Certificate B becomes the active certificate approximately 45 days after it has been issued. At this stage, Certificate A is marked as Inactive and Certificate B becomes the Active certificate. Certificate B will be used to recognize and authenticate your devices. Ensure that your cloud services are configured with both Certificate A and Certificate B for correct operation. |
| 4 | Certificate A has expired. You can now remove Certificate A from your cloud services. |
| 5 | Certificate B is valid for 2 years. |
Tip
The dates in the image are provided for illustration only and will vary from customer to customer.
You may need to roll certificates to handle certificate expiration. For more information on rolling certificates, see Azure IoT managed services, or consult the documentation provided by your preferred back-end service.