Configure a credential in Azure Device Registry (preview)

When you enable Microsoft-backed X.509 certificate management in your Azure Device Registry (ADR) namespace, you create a single credential resource within that ADR namespace. A credential manages one unique root CA within your own cloud PKI.

Important

Azure IoT Hub with ADR integration and Microsoft-backed X.509 certificate management is in public preview and isn't recommended for production workloads. For more information, see the FAQ: What is new in IoT Hub?

Microsoft manages the PKI and root CA for your ADR namespace, so you don't need on-premises PKI infrastructure.

When you configure a credential, Microsoft:

Generates and stores the root certificate in Azure Key Vault Managed HSM
Manages the root certificate lifecycle
Lets you create issuing CAs (policies) that the root CA signs

You can configure a root CA credential in your ADR namespace by using the Azure portal or Azure CLI.

An active Azure subscription. If you don't have an Azure subscription, create a free account.
An existing Azure Device Registry namespace. For setup instructions, see Deploy Azure IoT Hub with ADR integration and certificate management.
Ensure that you have the privilege to perform role assignments within your target ADR namespace scope. Performing role assignments in Azure requires a privileged role, such as Owner or User Access Administrator at the appropriate scope.

An active Azure subscription. If you don't have an Azure subscription, create a free account.
An existing Azure Device Registry namespace. For setup instructions, see Deploy Azure IoT Hub with ADR integration.
Ensure that you have the privilege to perform role assignments within your target ADR namespace scope. Performing role assignments in Azure requires a privileged role, such as Owner or User Access Administrator at the appropriate scope.
Azure CLI installed on your machine.
1. Install Azure CLI. Run az version to see the installed Azure CLI version and dependent libraries, and run az upgrade to install the latest version.
2. Sign in to Azure by running az login.
3. Install the azure-iot extension when prompted on first use. To make sure you're using the latest version of the extension, run az extension update --name azure-iot.

Configure a credential

Azure portal
Azure CLI

Follow these steps to configure your root CA credential.

Sign in to the Azure portal.
Search for and select Azure Device Registry from the search bar.
In the resource menu, select Namespaces, and then select your ADR namespace from the list.
In the resource menu of your ADR namespace, select Credential policies (Preview) under Namespace resources.
On the Credential policies (Preview) page, select Enable from the Enable certificate management dialog.
Azure provisions a root CA credential for your namespace. This process takes a few moments to complete.
After provisioning is complete, your root CA credential is ready to use. The credential is displayed on the Credential policies (Preview) page.

Follow these steps to configure your root CA credential.

Run az iot ns credential create to enable credential management and create a new root CA for your ADR namespace.
```
az iot adr ns credential create --namespace <namespace> \
  --resource-group <resource_group>
```
In the command, replace the following placeholders with your own information:
- <namespace>: The name of an existing ADR namespace.
- <resource_group>: The name of the resource group for the ADR namespace.
Run az iot adr ns policy create to create a new policy for your ADR namespace. The policy is configured to use the ECC certificate type and remains valid for 30 days.
```
az iot adr ns policy create --name <policy> \
  --namespace <namespace> \
  --resource-group <resource_group> \
  --cert-key-type ECC \
  --cert-validity-days 30
```
In the command, replace the following placeholders with your own information:
- <policy>: The name of the policy to be created for the ADR namespace.
- <namespace>: The name of an existing ADR namespace.
- <resource_group>: The name of the resource group for the ADR namespace.
Run az iot adr ns credential sync to synchronize the credentials between your ADR namespace and your linked IoT hub.
```
az iot adr ns credential sync --ns myNamespace -g myRG
```
In the command, replace the following placeholders with your own information:
- <policy>: The name of an existing policy for the ADR namespace.
- <namespace>: The name of an existing ADR namespace.
- <resource_group>: The name of the resource group for the ADR namespace.

Verify credential configuration

After you enable credential management, verify that your root CA credential is provisioned by running the az iot adr ns credential show command:

az iot adr ns credential show --namespace <namespace> \
  --resource-group <resource_group>

In the command, replace the following placeholders with your own information:

<namespace>: The name of an existing ADR namespace.
<resource_group>: The name of the resource group for the ADR namespace.

This command displays the details of your root CA credential, including its provisioning status and certificate information.

You can now create issuing CAs (policies) with either a Microsoft-issued certificate or an external CA within your namespace that is signed by your unique credential. To issue and manage X.509 certificates for your IoT devices, use these policies with Device Provisioning Service.

Next steps

After you configure your root CA credential, you can:

Create issuing CA policies within your namespace to issue X.509 certificates for your IoT devices
Link an IoT hub to your ADR namespace to enable certificate-based authentication for your devices
Set up Device Provisioning Service enrollments to provision devices with issued certificates

For more information about certificate management and the complete workflow, see:

Feedback

Was this page helpful?

Last updated on 2026-04-15