Deploy Azure IoT Hub with ADR integration and certificate management (preview)

Additional prerequisites for Azure portal

Before you begin, make sure you have:

• An Azure resource group to organize your IoT hub and related resources. Create the resource group and resources in a supported region. For more information, see Create a resource group.
• Assigned the Contributor role to the Azure IoT Hub service at the resource group level. When you select members during the role assignment, search for and select Azure IoT Hub from the list of service principals. For more information, see Assign Azure roles using the Azure portal.

Overview

Use the Azure portal to create an IoT hub with Azure Device Registry and certificate management integration.

The setup process in this article includes the following steps:

1. Set up your ADR namespace with system-assigned managed identity and assign necessary roles.
2. Create a custom credential policy for your namespace.
3. Create an IoT hub linked to your ADR namespace with a user-assigned managed identity.
4. Create a DPS instance and link it to your ADR namespace.
5. Link your IoT hub to the DPS instance.
6. Sync credential policies from your namespace to your IoT hubs.
7. Create an enrollment group and assign a policy to enable device onboarding.

Set up your ADR namespace

In this section, you set up your Azure Device Registry (ADR) namespace, enable managed identities, assign the necessary contributor role, and create a custom credential policy. These steps prepare your environment to securely manage device identities and certificates, and ensure your IoT hub can use ADR for device onboarding and certificate management.

Create an ADR namespace with system-assigned managed identity

When you create a namespace with a system-assigned managed identity, the process also creates a credential known as root CA and a default policy known as intermediate CA. Certificate management uses these credentials and policies to onboard devices to the namespace.

1. Sign in to the Azure portal.

2. Search for and select Azure Device Registry.

3. Select Namespaces > Create.

4. On the Basics tab, fill in the fields as follows:

   Property	Value
   Subscription	Select the subscription to use for your ADR namespace.
   Resource group	Select or create the resource group that you want to use for your IoT hub.
   Name	Enter a name for your ADR namespace. Your namespace name can only contain lowercase letters and hyphens ('-') in the middle of the name, but not at the beginning or end. For example, the name "msft-namespace" is valid.
   Region	ADR integration and certificate management functionalities are in preview and only available in certain regions. See the supported regions. Select the region, closest to you, where you want your hub to be located.

   

5. Select Next.

6. In the Identity tab, enable a system-assigned managed identity and a credential resource for your namespace. For more information about how ADR works with managed identities and credential resources, see What is certificate management.

   • Managed identities allow your namespace to authenticate to Azure services without storing credentials in your code.
   • Credential resources securely store and manage device authentication credentials, such as API keys or certificates, for devices connecting to your namespace. When you enable this feature, you can set policies to control how certificates are issued and managed for your devices.

   

7. Select Next.

8. In the Tags tab, you can optionally add tags to organize your ADR namespace. Tags are key-value pairs that help you manage and identify your resources. Use tags to filter and group your resources in the Azure portal.

9. Select Next.

10. Review your settings, then select Create to create your ADR namespace.

    Note

    The creation of the namespace with system-assigned managed identity might take up to five minutes.

Get the principal ID for your namespace

To complete some configuration steps after you create the IoT hub, you need the principal ID for your ADR namespace. This value is used to grant permissions and link resources securely.

1. In the Azure portal, go to the ADR namespace you created.
2. On the Overview page, at the top right-hand side, select JSON view.
3. Locate the identity section and find the value for principalId.
4. Copy the principal ID value to use with role assignments for your IoT hub instance.

Assign roles to your managed identity

After you create your ADR namespace, grant the required permissions to your user-assigned managed identity. The user-assigned managed identity is used to securely access other Azure resources, such as ADR namespace and DPS. If you don't have a user-assigned managed identity, create one in the Azure portal. For more information, see Create a user-assigned managed identity in the Azure portal.

First grant your user-managed identity the Azure Device Registry Onboarding role:

1. In the same Access control (IAM) pane for your ADR namespace, select + Add > Add role assignment again.
2. In the Role field, search for and select Azure Device Registry Onboarding. This role allows your managed identity to onboard devices using ADR credential policies.
3. Select Next.
4. In Assign access to, choose Managed identity.
5. Select Select members, then choose User-assigned managed identity. Search for your identity and select it.
6. Select Review + assign to finish. After the assignment propagates, your managed identity will have the necessary onboarding permissions.

Repeat these steps to assign the Azure Device Registry Contributor role:

1. In the Azure portal, go to Home > Azure Device Registry > select your ADR namespace.
2. In the left pane, select Access control (IAM).
3. Select + Add > Add role assignment.
4. In the Role field, search for and select Azure Device Registry Contributor. This role gives your managed identity the permissions ADR needs for setup and operation.
5. Select Next.
6. In Assign access to, choose Managed identity.
7. Select Select members, then choose User-assigned managed identity. Search for your identity and select it.
8. Select Review + assign to finish. After the assignment propagates, you can select the user-assigned managed identity when you create your IoT hub.

Create a custom policy for your namespace

Create custom policies within your ADR namespace to define how certificates are issued and managed for your devices. Policies allow you to set parameters such as certificate validity periods and subjects. Editing or disabling a policy isn't supported in preview.

1. In the Azure portal, search for and select Azure Device Registry.

2. Go to the Namespaces page.

3. Select your ADR namespace.

4. In the namespace page, under Namespace resources, select Credential policies (Preview).

   

5. Select Enable credential resource to turn on credential policies for your namespace, if they aren't already active.

6. In the Credential policies page, select + Create to create a new policy.

7. A pane appears where you can configure the policy settings. In the Basics tab, complete the fields as follows:

   Property	Value
   Name	Enter a unique name for your policy. The name must be between 3 and 50 alphanumeric characters and can include hyphens ('-').
   Validity period (days)	Enter the number of days the issued certificates are valid.

8. Select Next > Create.

9. After it's created, select Go to resource and select the namespace.

10. To review the policy, select Credential policies to see the policy name and validity period.

Create an IoT hub in Azure portal

In this section, you create a new IoT hub instance with the ADR namespace and your user-assigned managed identity.

1. In the Azure portal, search for and select Azure IoT Hub.

2. In the IoT Hub page, select + Create to create a new IoT hub.

3. On the Basics tab, complete the fields as follows:

   Important

   Because the IoT hub will be publicly discoverable as a DNS endpoint, be sure to avoid entering any sensitive or personally identifiable information when you name it.

   Property	Value
   Subscription	Select the subscription to use for your hub.
   Resource group	Select a resource group or create a new one. To create a new one, select Create new and fill in the name you want to use.
   IoT hub name	Enter a name for your hub. This name must be globally unique, with a length between 3 and 50 alphanumeric characters. The name can also include the dash ('-') character.
   Region	ADR integration and certificate management functionalities are in preview and only available in certain regions. See the supported regions. Select the region, closest to you, where you want your hub to be located.
   Tier	Select the Preview tier. To compare the features available to each tier, select Compare tiers.
   Daily message limit	Select the maximum daily quota of messages for your hub. The available options depend on the tier you select for your hub. To see the available messaging and pricing options, select See all options and select the option that best matches the needs of your hub. For more information, see IoT Hub quotas and throttling.
   Device registry namespace	Select the ADR namespace you created in the previous section.
   User-managed identity	Select the user-assigned managed identity you associated to the ADR namespace and link it to your IoT hub.

   

   Note

   Prices shown are for example purposes only.

Configure the networking, management, and add-ons settings

After you complete the Basics tab, configure your IoT hub by following these steps:

1. Select Next: Networking to continue creating your hub.

2. On the Networking tab, complete the fields as follows:

   Property	Value
   Connectivity configuration	Choose the endpoints that devices can use to connect to your IoT hub. Accept the default setting, Public access, for this example. You can change this setting after the IoT hub is created. For more information, see IoT Hub endpoints.
   Minimum TLS Version	Select the minimum TLS version supported by your IoT hub. Once the IoT hub is created, you can't change this value. Accept the default setting, 1.2, for this example.

   

3. Select Next: Management to continue creating your hub.

4. On the Management tab, accept the default settings. If desired, you can modify any of the following fields:

   Property	Value
   Permission model	Part of role-based access control, this property decides how you manage access to your IoT hub. Allow shared access policies or choose only role-based access control. For more information, see Control access to IoT Hub by using Microsoft Entra ID.
   Assign me	You might need access to IoT Hub data APIs to manage elements within an instance. If you have access to role assignments, select IoT Hub Data Contributor role to grant yourself full access to the data APIs. To assign Azure roles, you must have Microsoft.Authorization/roleAssignments/write permissions, such as User Access Administrator or Owner.
   Device-to-cloud partitions	This property relates the device-to-cloud messages to the number of simultaneous readers of the messages. Most IoT hubs need only four partitions.

   

5. Select Next: Add-ons to continue to the next screen.

6. On the Add-ons tab, accept the default settings. If desired, you can modify any of the following fields:

   Property	Value
   Enable Device Update for IoT Hub	Turn on Device Update for IoT Hub to enable over-the-air updates for your devices. If you select this option, you're prompted to provide information to provision a Device Update for IoT Hub account and instance. For more information, see What is Device Update for IoT Hub?
   Enable Defender for IoT	Turn Defender for IoT on to add an extra layer of protection to IoT and your devices. This option isn't available for hubs in the free tier. For more information, see Security recommendations for IoT Hub in Microsoft Defender for IoT documentation.

   

   Note

   Prices shown are for example purposes only.

7. Select Next: Tags to continue to the next screen.

   Tags are name/value pairs. You can assign the same tag to multiple resources and resource groups to categorize resources and consolidate billing. In this article, you don't add any tags. For more information, see Use tags to organize your Azure resources and management hierarchy.

   

8. Select Next: Review + create to review your choices.

9. Select Create to start the deployment of your new hub. Your deployment might progress for a few minutes while the hub is being created. Once the deployment is complete, select Go to resource to open the new hub.

Link your user-assigned managed identity to the IoT hub

After you create your IoT hub, you need to associate your user-assigned managed identity with the hub. This step enables the IoT hub to use the managed identity for secure access to other Azure resources, such as the ADR namespace.

1. In the Azure portal, go to your IoT hub resource.
2. In the left pane, under Security settings, select Identity.
3. At the top of the Identity pane, select the User-assigned tab.
4. Select Associate.
5. Choose the user-assigned managed identity you used with your namespace and select Add.

Assign roles to the ADR namespace principal ID on your IoT hub

To enable secure integration between your IoT hub and ADR namespace, assign roles to the ADR namespace principal ID on your IoT hub instance. This step ensures the ADR namespace can manage device identities and registry operations in your hub.

1. In the Azure portal, go to your IoT hub resource.
2. In the left pane, select Access control (IAM).
3. Select + Add > Add role assignment.
4. In the Role field, select the Privileged administrator roles tab.
5. Search for and select Contributor.
6. Select Next.
7. Select Select members, then paste in the ADR namespace principal ID you copied in a previous step. Select the matching identity.
8. Select Review + assign to finish.

Repeat these steps to assign the IoT Hub Registry Contributor role:

1. Select + Add > Add role assignment again.
2. In the Role field, search for and select IoT Hub Registry Contributor.
3. Select Next.
4. In Assign access to, choose Managed identity.
5. Select Select members, then paste in the ADR namespace principal ID you copied in a previous step. Select the matching identity.
6. Select Review + assign to finish.

Create a DPS instance

After you create your IoT hub and your namespace, create a new DPS instance.

1. In the Azure portal, search for and select Device Provisioning Service.

2. In Device Provisioning Services, select + Create to create a new DPS instance.

3. On the Basics tab, complete the fields as follows:

   Property	Value
   Subscription	Select the subscription to use for your Device Provisioning Service instance.
   Resource group	Select the same resource group that contains the IoT hub that you created in the previous steps. By putting all related resources in a group together, you can manage them together.
   Name	Provide a unique name for your new Device Provisioning Service instance. If the name you enter is available, a green check mark appears.
   Region	Select the same region where you created your IoT hub and ADR namespace in the previous steps.

   

4. Select Review + create to validate your provisioning service.

5. Select Create to start the deployment of your Device Provisioning Service instance.

6. After the deployment completes, select Go to resource to view your Device Provisioning Service instance.

Add your namespace to DPS

After you create your DPS instance, link it to your ADR namespace so devices can be provisioned using ADR credential policies.

1. In the Azure portal, go to the DPS instance you just created.

2. On the Overview page, find the ADR namespace section.

3. Select the link to add the namespace.

   

4. Select your ADR namespace and the user-assigned managed identity.

5. Select Save.

After the link is established, your DPS instance can use the ADR namespace for device provisioning and certificate management.

Link the IoT hub and your Device Provisioning Service instance

Add a configuration to the DPS instance that sets the IoT hub to which the instance provisions IoT devices.

1. In the Settings menu of your DPS instance, select Linked IoT hubs.

2. Select Add.

3. On the Add link to IoT hub panel, provide the following information:

   Property	Value
   Subscription	Select the subscription containing the IoT hub that you want to link with your new Device Provisioning Service instance.
   IoT hub	Select the IoT hub to link with your new Device Provisioning System instance.
   Access Policy	Select iothubowner (RegistryWrite, ServiceConnect, DeviceConnect) as the credentials for establishing the link with the IoT hub.

   

4. Select Save.

5. Select Refresh. You should now see the selected hub under the list of Linked IoT hubs.

Sync policies to IoT hubs

Synchronize a policy you created within your ADR namespace to the IoT hub linked to that namespace. This synchronization enables IoT Hub to trust any devices authenticating with a leaf certificate issued by the policy's issuing CA (ICA).

1. In the Azure portal, go to the ADR namespace resource you created earlier.
2. In the left pane, select Namespace resources > Credential policies (Preview).
3. In the list, select the credential policy you want to synchronize.
4. At the top, select Sync all.
5. Wait for the confirmation message that indicates the synchronization succeeded.

If you select to sync more than one policy, the process syncs policies to their respective IoT hubs. You can't undo a sync operation.

Create an enrollment group and assign a policy

To provision devices with leaf certificates, you need to create an enrollment group and assign the policy you created within your ADR namespace. The allocation-policy defines the onboarding authentication mechanism DPS uses before issuing a leaf certificate. The default attestation mechanism is a symmetric key.

1. In the Azure portal, search for and select Device Provisioning Services.

2. Search for and select the DPS instance you created previously.

3. In the Settings menu of your DPS instance, select Manage enrollments.

4. In the Manage enrollments page, select either the Enrollment groups or Individual enrollments tab based on your provisioning needs.

5. Select + Add enrollment group or + Add individual enrollment to create a new enrollment.

6. In the Registration + provisioning page, complete the fields as follows:

   Property	Value
   Attestation mechanism	Select X.509 intermediate certificate as the attestation method.
   X.509 certificate settings	Upload the intermediate certificate files. Enrollments have one or two certificates, known as primary and secondary certificate files.
   Group name	Enter a name for your enrollment group. Skip this field if you're creating an individual enrollment.
   Provisioning status	Select Enabled to enable the enrollment from provisioning.
   Reprovision policy	Specify the reprovisioning policy for the enrollment. This policy determines how the enrollment behaves during device reprovisioning.

7. Select and complete IoT hubs and Device settings tabs as appropriate for your environment.

8. Select the Credential policies (Preview) tab and the Policy you want to assign to the enrollment group or individual enrollment.

   

9. Select Review + create and Create to finalize the enrollment.

Additional prerequisites for Azure CLI

Before you begin, make sure you have:

• Azure CLI installed. Follow the steps to install the Azure CLI.

• Installed the Azure IoT CLI extension with previews enabled to access the ADR integration and certificate management functionalities for IoT Hub:

  1. Check for existing Azure CLI extension installations.

     az extension list
     

  2. Remove any existing azure-iot installations.

     az extension remove --name azure-iot
     

  3. Install the azure-iot extension from the index with previews enabled,

     az extension add --name azure-iot --allow-preview
     

     or download the .whl file from the GitHub releases page to install the extension manually.

     az extension add --upgrade --source https://github.com/Azure/azure-iot-cli-extension/releases/download/v0.30.0b1/azure_iot-0.30.0b1-py3-none-any.whl
     

  4. After the install, validate your azure-iot extension version is at least 0.30.0b1.

     az extension list
     

Overview

Use the Azure CLI commands to create an IoT Hub with ADR integration and certificate management.

The setup process in this article includes the following steps:

1. Create a resource group
2. Configure the necessary app privileges
3. Create a user-assigned managed identity
4. Create an ADR namespace with system-assigned managed identity
5. Create a credential (root CA) and policy (issuing CA) scoped to that namespace
6. Create an IoT Hub (preview) with linked namespace and managed identity
7. Create a DPS with linked IoT Hub and namespace
8. Sync your credential and policies (CA certificates) to IoT Hub
9. Create an enrollment group and link to your policy to enable certificate provisioning

Prepare your environment

To prepare your environment to use Azure Device Registry, complete the following steps:

1. Open a terminal window.

2. To sign in to your Azure account, run az login.

3. To list all subscriptions and tenants you have access to, run az account list.

4. If you have access to multiple Azure subscriptions, set your active subscription where your IoT devices are created by running the following command.

   az account set --subscription "<your subscription name or ID>"
   

5. To display your current account details, run az account show. Copy both of the following values from the output of the command, and save them to a safe location.

   • The id GUID. You use this value to provide your Subscription ID.
   • The tenantId GUID. You use this value to update your permissions using Tenant ID.

Configure your resource group, permissions, and managed identity

To create a resource group, role, and permissions for your IoT solution, complete the following steps:

1. Create a resource group for your environment.

   az group create --name <RESOURCE_GROUP_NAME> --location <REGION>
   

2. Assign a Contributor role to IoT Hub on the resource group level. The AppId value, which is the principal ID for IoT Hub, is 89d10474-74af-4874-99a7-c23c2f643083 and it's the same for all Hub apps.

   az role assignment create --assignee "89d10474-74af-4874-99a7-c23c2f643083" --role "Contributor" --scope "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>"
   

3. Create a new user-assigned managed identity (UAMI).

   az identity create --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME> --location <REGION>
   

4. Retrieve the resource ID of the managed identity. You need the resource ID to assign roles, configure access policies, or link the identity to other resources.

   UAMI_RESOURCE_ID=$(az identity show --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME> --query id -o tsv)
   

Create a new ADR namespace

In this section, you create a new ADR namespace with a system-assigned managed identity. This process automatically generates a root CA credential and an issuing CA policy for the namespace. For more information on how credentials and policies are used to sign device leaf certificates during provisioning, see Certificate Management.

1. Create a new ADR namespace. Your namespace name may only contain lowercase letters and hyphens ('-') in the middle of the name, but not at the beginning or end. For example, the name "msft-namespace" is valid.
   The --enable-credential-policy command creates credential (root CA) and default policy (issuing CA) for this namespace. You can configure the name for this policy using the --policy-name command. By default, a policy can issue certificates with a validity of 30 days.

   az iot adr ns create --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --location <REGION> --enable-credential-policy true --policy-name <POLICY_NAME>
   

   Tip

   You can optionally create a custom policy by adding the --cert-subject and --cert-validity-days parameters. For more information, see Create a custom policy.

   Note

   The creation of the ADR namespace with system-assigned managed identity might take up to 5 minutes.

2. Verify that the namespace with a system-assigned managed identity, or principal ID, is created.

   az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
   

3. Verify that a credential and policy named are created.

   az iot adr ns credential show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
   az iot adr ns policy show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --name <POLICY_NAME>
   

   Note

   If you did not assign a policy name, the policy is created with the name "default".

Assign UAMI role to access the ADR namespace

In this section, you assign the Azure Device Registry Contributor role to the managed identity and scope it to the namespace. This custom role allows for full access to IoT devices within the ADR namespace.

1. Retrieve the principal ID of the User-Assigned Managed Identity. This ID is needed to assign roles to the identity.

   UAMI_PRINCIPAL_ID=$(az identity show --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP> --query principalId -o tsv)
   

2. Retrieve the Resource ID of the ADR Namespace. This ID is used as the scope for the role assignment.

   NAMESPACE_RESOURCE_ID=$(az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP> --query id -o tsv)
   

3. Assign the Azure Device Registry Contributor role to the managed identity. This role grants the managed identity the necessary permissions, scoped to the namespace.

   az role assignment create --assignee $UAMI_PRINCIPAL_ID --role "a5c3590a-3a1a-4cd4-9648-ea0a32b15137" --scope $NAMESPACE_RESOURCE_ID
   

Create an IoT Hub with ADR integration

1. Create a new IoT Hub that is linked to the ADR namespace and with the UAMI created earlier.

   az iot hub create --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --location <HUB_LOCATION> --sku GEN2 --mi-user-assigned $UAMI_RESOURCE_ID --ns-resource-id $NAMESPACE_RESOURCE_ID --ns-identity-id $UAMI_RESOURCE_ID
   

   Important

   Because the IoT hub will be publicly discoverable as a DNS endpoint, be sure to avoid entering any sensitive or personally identifiable information when you name it.

2. Verify that the IoT Hub has correct identity and ADR properties configured.

   az iot hub show --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --query identity --output json
   

Assign IoT Hub roles to access the ADR namespace

1. Retrieve the principal ID of the ADR namespace's managed identity. This identity needs permissions to interact with the IoT Hub.

   ADR_PRINCIPAL_ID=$(az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP> --query identity.principalId -o tsv)
   

2. Retrieve the resource ID of the IoT Hub. This ID is used as the scope for role assignments.

   HUB_RESOURCE_ID=$(az iot hub show --name <HUB_NAME> --resource-group <RESOURCE_GROUP> --query id -o tsv)
   

3. Assign the "Contributor" role to the ADR identity. This grants the ADR namespace's managed identity Contributor access to the IoT Hub. This role allows broad access, including managing resources, but not assigning roles.

   az role assignment create --assignee $ADR_PRINCIPAL_ID --role "Contributor" --scope $HUB_RESOURCE_ID
   

4. Assign the "IoT Hub Registry Contributor" role to the ADR identity. This grants more specific permissions to manage device identities in the IoT Hub. This is essential for ADR to register and manage devices in the hub.

   az role assignment create --assignee $ADR_PRINCIPAL_ID --role "IoT Hub Registry Contributor" --scope $HUB_RESOURCE_ID
   

Create a Device Provisioning Service instance with ADR integration

1. Create a new DPS instance linked to your ADR namespace created in the previous sections. Your DPS instance must be located in the same region as your ADR namespace.

   az iot dps create --name <DPS_NAME> --resource-group <RESOURCE_GROUP> --location <LOCATION> --mi-user-assigned $UAMI_RESOURCE_ID --ns-resource-id $NAMESPACE_RESOURCE_ID --ns-identity-id $UAMI_RESOURCE_ID
   

2. Verify that the DPS has the correct identity and ADR properties configured.

   az iot dps show --name <DPS_NAME> --resource-group <RESOURCE_GROUP> --query identity --output json
   

Link your IoT Hub to the Device Provisioning Service instance

1. Link the IoT Hub to your DPS.

   az iot dps linked-hub create --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP> --hub-name <HUB_NAME>
   

2. Verify that the IoT Hub appears in the list of linked hubs for the DPS.

   az iot dps linked-hub list --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP>
   

Run ADR credential synchronization

Synchronize your credential and policies to the IoT Hub. This step ensures that the IoT Hub registers the CA certificates and trusts any leaf certificates issued by your configured policies.

az iot adr ns credential sync --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP>

Validate the hub CA certificate

Validate that your IoT Hub has registered its CA certificate.

az iot hub certificate list --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP>

Create an enrollment in DPS

To provision devices using leaf certificates, create an enrollment group in DPS and assign it to the appropriate credential policy with the --credential-policy parameter.

The following command creates an enrollment group, using symmetric key attestation by default:

az iot dps enrollment-group create --dps-name <DPS_NAME> --resource-group <RESOURCE_GROUP> --enrollment-id <ENROLLMENT_ID> --credential-policy <POLICY_NAME>

Your IoT Hub with ADR integration and certificate management is now set up and ready to use.

Optional commands

The following commands help you manage your ADR namespaces, disable devices, create custom policies, and delete resources when they are no longer needed.

Manage your namespaces

1. List all namespaces in your resource group.

   az iot adr ns list --resource-group <RESOURCE_GROUP_NAME>
   

2. Show details of a specific namespace.

   az iot adr ns show --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
   

3. List all policies in your namespace.

   az iot adr ns policy list --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
   

4. Show details of a specific policy.

   az iot adr ns policy show --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --name <POLICY_NAME>
   

5. List all credentials in your namespace.

   az iot adr ns credential list --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
   

Disable devices

1. List all devices in your IoT Hub.

   az iot hub device-identity list --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME>
   

2. Disable a device by updating its status to disabled. Make sure to replace <MY_DEVICE_ID> with the device ID you want to disable.

   az iot hub device-identity update --hub-name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME> -d <MY_DEVICE_ID> --status disabled
   

3. Run the device again and verify that it is unable to connect to an IoT Hub.

Create a custom policy

Create a custom policy using the az iot adr ns policy create command. Set the name, certificate subject, and validity period for the policy following these rules:

• The policy name value must be unique within the namespace. If you try to create a policy with a name that already exists, you receive an error message.
• The certificate subject cert-subject value must be unique across all policies in the namespace. If you try to create a policy with a subject that already exists, you receive an error message.
• The validity period cert-validity-days value must be between 1 and 30 days. If you try to create a policy with a validity period outside this range, you receive an error message.

The following example creates a policy named "custom-policy" with a subject of "CN=TestDevice" and a validity period of 30 days.

az iot adr ns policy create --name "custom-policy" --namespace <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME> --cert-subject "CN=TestDevice" --cert-validity-days "30"

Delete resources

To delete your ADR namespace, you must first delete any IoT Hubs linked to the namespace.

az iot hub delete --name <HUB_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot adr ns delete --name <NAMESPACE_NAME> --resource-group <RESOURCE_GROUP_NAME>
az iot dps delete --name <DPS_NAME> --resource-group <RESOURCE_GROUP_NAME> 
az identity delete --name <USER_IDENTITY> --resource-group <RESOURCE_GROUP_NAME>

Overview

Use the provided PowerShell script to automate the setup of your IoT Hub with Azure Device Registry integration. The script performs all the necessary steps to create the required resources and link them together, including:

1. Create a resource group
2. Configure the necessary app privileges
3. Create a user-assigned managed identity
4. Create an ADR namespace with system-assigned managed identity
5. Create a credential (root CA) and policy (issuing CA) scoped to that namespace
6. Create an IoT Hub (preview) with linked namespace and managed identity
7. Create a DPS with linked IoT Hub and namespace
8. Sync your credential and policies (CA certificates) to IoT Hub
9. Create an enrollment group and link to your policy to enable certificate provisioning

Prepare your environment

1. Download PowerShell 7 for Windows.
2. Navigate to the GitHub repository and download the Scripts folder, which contains the script file, iothub-adr-certs-setup-preview.ps1.

Customize the script variables

Open the script file in a text editor and modify the following variables to match your desired configuration.

• TenantId: Your tenant ID. You can find this value by running az account show in your terminal.
• SubscriptionId: Your subscription ID. You can find this value by running az account show in your terminal.
• ResourceGroup: The name of your resource group.
• Location: The Azure region where you want to create your resources. Check out the available locations for preview features in the Supported regions section.
• NamespaceName: Your namespace name may only contain lowercase letters and hyphens ('-') in the middle of the name, but not at the beginning or end. For example, "msft-namespace" is a valid name.
• HubName: Your hub name can only contain lowercase letters and numerals.
• DpsName: The name of your Device Provisioning Service instance.
• UserIdentity: The user-assigned managed identity for your resources.
• WorkingFolder: The local folder where your script is located.

Run the script interactively

1. Open the script and run in PowerShell 7+ as an administrator. Navigate to the folder containing your script and run .\iothub-adr-certs-setup-preview.ps1.

2. If you run into an execution policy issue, try running powershell -ExecutionPolicy Bypass -File .\iothub-adr-certs-setup-preview.ps1.

3. Follow the guided prompts:

   • Press Enter to proceed with a step
   • Press s or S to skip a step
   • Press Ctrl + C to abort

Monitor execution and validate the resources

1. The script continues execution when warnings are encountered and only stops if a command returns a non-zero exit code. Monitor the console for red ERROR messages, which indicate issues that require attention.

2. Once the script completes, validate the creation of your resources by visiting your new Resource Group on the Azure portal. You should see the following resources created:

   • IoT Hub instance
   • Device Provisioning Service (DPS) instance
   • Azure Device Registry (ADR) namespace
   • User-Assigned Managed Identity (UAMI)