Edit

Share via

Get started with ADR integration and Microsoft-backed X.509 certificate management in IoT Hub (preview)

This article explains how to create a new IoT Hub with Azure Device Registry (ADR) integration and Microsoft-backed X.509 certificate management.

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?.

Prerequisites

  • An active Azure subscription. If you don't have an Azure subscription, create a free account.

  • If you don't have the Azure CLI installed, follow the steps to install the Azure CLI.

  • Install 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 greater than 0.30.0b1.

      az extension list

  • Ensure that you have the privilege to perform role assignments within your target scope. Performing role assignments in Azure requires a privileged role, such as Owner or User Access Administrator at the appropriate scope.

Choose a deployment method

To use certificate management, you must also set up IoT Hub, ADR, and the Device Provisioning Service (DPS). If you prefer, you can choose not to enable certificate management and configure only IoT Hub with ADR.

To set up your IoT Hub with ADR integration and certificate management, you can use Azure CLI or a script that automates the setup process.

Deployment method Description
Select Azure CLI at the top of the page Use the Azure CLI to create a new IoT Hub, DPS instance, and ADR namespace and configure all necessary settings.
Select PowerShell script at the top of the page Use a PowerShell script (Windows only) to automate the creation of a new IoT Hub, DPS instance, and ADR namespace and configure all necessary settings.

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 ADR namespace
  9. Create an enrollment group and link to your policy to enable certificate provisioning

Important

During the preview period, IoT Hub with ADR integration and certificate management features enabled on top of IoT Hub are available free of charge. Device Provisioning Service (DPS) is billed separately and isn't included in the preview offer. For details on DPS pricing, see Azure IoT Hub pricing.

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.

Note

Credentials are optional. You can also create a namespace without a managed identity by omitting the --enable-credential-policy and --policy-name flags.

  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

  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:

Note

If you created a policy with a different name from "default", ensure that you use that policy name after the --credential-policy parameter.

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 and DPS instances 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 ADR namespace
  9. Create an enrollment group and link to your policy to enable certificate provisioning

Important

During the preview period, IoT Hub with ADR integration and certificate management features enabled on top of IoT Hub are available free of charge. Device Provisioning Service (DPS) is billed separately and isn't included in the preview offer. For details on DPS pricing, see Azure IoT Hub pricing.

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.

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.

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

Note

The creation of your ADR namespace, IoT Hub, DPS, and other resources may take up to 5 minutes each.

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)

Next steps

At this point, your IoT Hub with ADR integration and certificate management is set up and ready to use. You can now start onboarding your IoT devices to the hub using the Device Provisioning Service (DPS) instance and manage your IoT devices securely using the policies and enrollments you have set up.

New: Certificate management is supported across select DPS Device SDKs. You can now onboard devices using Microsoft-backed X.509 certificate management with the following SDK samples:

  • Last updated on