How to link and manage IoT hubs

Azure IoT Hub Device Provisioning Service (DPS) can provision devices across one or more IoT hubs. Before DPS can provision devices to an IoT hub, it must be able to write to the IoT hub device registry. This article provides instruction on how to link IoT hubs and manage them in your DPS instance. Once linked, an IoT hub can be used in an allocation policy. Allocation policies determine how devices are assigned to IoT hubs by DPS.

Linked IoT hub settings

The Device Provisioning Service can only provision devices to IoT hubs that have been linked to it. Linking an IoT hub to a DPS instance gives the DPS instance read/write permissions to the IoT hub's device registry. With these permissions, DPS can register a device ID and set the initial configuration in the device twin. Linked IoT hubs may be in any Azure region. You may link hubs in other subscriptions to your DPS instance.

After an IoT hub is linked to DPS, it's eligible to participate in allocation. Whether and how it participates in allocation depends on settings in the enrollment that a device provisions through and settings on the linked IoT hub itself.

The following settings control how DPS uses linked IoT hubs:

• Connection string: Sets the IoT Hub connection string that DPS uses to connect to the linked IoT hub. The connection string is based on one of the IoT hub's shared access policies. DPS needs the following permissions on the IoT hub: RegistryWrite and ServiceConnect. The connection string must be for a shared access policy that has these permissions. To learn more about IoT Hub shared access policies, see IoT Hub access control and permissions.

• Allocation weight: Determines the likelihood of an IoT hub being selected when DPS hashes device assignment across a set of IoT hubs. The value can be between one and 1000. The default is one (or null). Higher values increase the IoT hub's probability of being selected.

• Apply allocation policy: Sets whether the IoT hub participates in allocation policy. The default is Yes (true). If set to No (false), devices aren't assigned to the IoT hub. The IoT hub can still be selected on an enrollment, but it won't participate in allocation. You can use this setting to temporarily or permanently remove an IoT hub from participating in allocation; for example, if it's approaching the allowed number of devices.

To learn about DPS allocation policies and how linked IoT hubs participate in them, see Manage allocation policies.

Limitations

• There are some limitations when working with linked IoT hubs and private endpoints. For more information, see Private endpoint limitations.

• The linked IoT Hub must have Connect using shared access policies set to Allow.

Add a linked IoT hub

You can add IoT hubs that are inside or outside of your subscription. When you link an IoT hub, it might or might not be available for allocations in existing enrollments:

• For enrollments that don't explicitly set the IoT hubs to apply allocation policy to, a newly linked IoT hub immediately begins participating in allocation.

• For enrollments that do explicitly set the IoT hubs to apply allocation policy to, you'll need to manually or programmatically add the new IoT hub to the enrollment settings for it to participate in allocation.

Azure portal

In the Azure portal, you can link an IoT hub either from the left menu of your DPS instance or from the enrollment when creating or updating an enrollment. In both cases, the IoT hub is scoped to the DPS instance (not just the enrollment).

To link an IoT hub to your DPS instance in the Azure portal:

1. On the left menu of your DPS instance, select Linked IoT hubs.

2. At the top of the page, select + Add.

3. On the Add link to IoT hub page, select the subscription that contains the IoT hub and then choose the name of the IoT hub from the IoT hub list.

4. After you select the IoT hub, choose an access policy that DPS will use to connect to the IoT hub. The Access Policy list shows all shared access policies defined on the selected IoT Hub that have both RegistryWrite and ServiceConnect permissions defined. The default is the iothubowner policy. Select the policy you want to use.

5. Select Save.

Note

In the Azure portal, you can't set the Allocation weight and Apply allocation policy settings when you add a linked IoT hub. Instead, update these settings after the IoT hub is linked.

Azure CLI

Use the az iot dps linked-hub create Azure CLI command to link an IoT hub to your DPS instance.

For example, the following command links an IoT hub named MyExampleHub using a connection string for its iothubowner shared access policy. This command leaves the Allocation weight and Apply allocation policy settings at their defaults, but you can specify values for these settings if you want to.

az iot dps linked-hub create --dps-name MyExampleDps --resource-group MyResourceGroup --connection-string "HostName=MyExampleHub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=XNBhoasdfhqRlgGnasdfhivtshcwh4bJwe7c0RIGuWsirW0=" --location westus

DPS also supports linking IoT Hubs using the Create or Update DPS resource REST API, Resource Manager templates, and the DPS Management SDKs.

Update a linked IoT hub

You can update the settings on a linked IoT hub to change its allocation weight, whether it can have allocation policies applied to it, and the connection string that DPS uses to connect to it. When you update the settings for an IoT hub, the changes take effect immediately, whether the IoT hub is specified on an enrollment or used by default.

Azure portal

In the Azure portal, you can update the Allocation weight and Apply allocation policy settings.

To update the settings for a linked IoT hub using the Azure portal:

1. On the left menu of your DPS instance, select Linked IoT hubs, then select the IoT hub from the list.

2. On the Linked IoT hub details page:

   

   • Use the Allocation weight slider or text box to choose a weight between one and 1000. The default is one.

   • Set the Apply allocation policy switch to specify whether the linked IoT hub should be included in allocation.

3. Save your settings.

Note

You can't update the connection string that DPS uses to connect to the IoT hub from the Azure portal. Instead, use the Azure CLI to update the connection string, or delete the linked IoT hub from your DPS instance and relink it. To learn more, see the Update keys for linked IoT hubs section.

Azure CLI

With the Azure CLI, you can update the Allocation weight, Apply allocation policy, and Connection string settings.

Use the az iot dps linked-hub update command to update the allocation weight or apply allocation policies settings. For example, the following command sets the allocation weight and apply allocation policy for a linked IoT hub:

az iot dps linked-hub update --dps-name MyExampleDps --resource-group MyResourceGroup --linked-hub MyExampleHub --allocation-weight 2 --apply-allocation-policy true

Use the az iot dps update command to update the connection string for a linked IoT hub. You can use the --set parameter along with the connection string for the IoT hub shared access policy you want to use. For details, see Update keys for linked IoT hubs.

DPS also supports updating linked IoT Hubs using the Create or Update DPS resource REST API, Resource Manager templates, and the DPS Management SDKs.

Delete a linked IoT hub

When you delete a linked IoT hub from your DPS instance, it will no longer be available to set in future enrollments. However, it might or might not be removed from allocations in existing enrollments:

• For enrollments that don't explicitly set the IoT hubs to apply allocation policy to, a deleted linked IoT hub is no longer available for allocation.

• For enrollments that do explicitly set the IoT hubs to apply allocation policy to, you'll need to manually or programmatically remove the IoT hub from the enrollment settings for it to be removed from participation in allocation. Failure to do so might result in an error when a device tries to provision through the enrollment.

Azure portal

To delete a linked IoT hub from your DPS instance in the Azure portal:

1. On the left menu of your DPS instance, select Linked IoT hubs.

2. From the list of IoT hubs, select the check box next to the IoT hub or IoT hubs you want to delete. Then select Delete at the top of the page and confirm your choice when prompted.

Azure CLI

Use the az iot dps linked-hub delete command to remove a linked IoT hub from the DPS instance. For example, the following command removes the IoT hub named MyExampleHub:

az iot dps linked-hub delete --dps-name MyExampleDps --resource-group MyResourceGroup --linked-hub MyExampleHub

DPS also supports deleting linked IoT Hubs from the DPS instance using the Create or Update DPS resource REST API, Resource Manager templates, and the DPS Management SDKs.

Update keys for linked IoT hubs

It may become necessary to either rotate or update the symmetric keys for an IoT hub that's been linked to DPS. In this case, you'll also need to update the connection string setting in DPS for the linked IoT hub.

Provisioning to an IoT hub will fail during the interim between updating a key on the IoT hub and updating your DPS instance with the new connections string based on that key. For this reason, we recommend using the Azure CLI to update your keys because you can update the connection string on the linked hub directly. With the Azure portal, you have to delete the IoT hub from your DPS instance and then relink it in order to update the connection string.

Azure portal

You can't update the connection string setting for a linked IoT Hub when using Azure portal. Instead, you need to delete the linked IoT hub from your DPS instance and then readd it.

To update symmetric keys for a linked IoT hub in the Azure portal:

1. On the left menu of your DPS instance in the Azure portal, select the IoT hub that you want to update one or more keys for.

2. On the Linked IoT hub details page, note down the values for Allocation weight and Apply allocation policy. You need these values when you relink the IoT hub to your DPS instance later. Then, select Manage Resource to go to the IoT hub.

3. On the left menu of the IoT hub, under Security settings, select Shared access policies.

4. On Shared access policies, under Manage shared access policies, select the policy that your DPS instance uses to connect to the linked IoT hub.

5. At the top of the page, select Regenerate primary key, Regenerate secondary key, or Swap keys, and confirm your choice when prompted.

6. Navigate back to your DPS instance.

7. Follow the steps in the Delete a linked IoT hub section to delete the IoT hub from your DPS instance.

8. Follow the steps in the Add a linked IoT hub section to relink the IoT hub to your DPS instance with the new connection string for the policy.

9. If you need to restore the allocation weight and apply allocation policy settings, follow the steps in the Update a linked IoT hub section using the values you saved in step 2.

Azure CLI

To update symmetric keys for a linked IoT hub with Azure CLS:

1. Use the az iot hub policy renew-key command to swap or regenerate the symmetric keys for the shared access policy on the IoT hub. For example, the following command renews the primary key for the iothubowner shared access policy on an IoT hub:

   az iot hub policy renew-key --hub-name MyExampleHub --name owner --rk primary
   

2. Use the az iot hub connection-string show command to get the new connection string for the shared access policy. For example, the following command gets the primary connection string for the iothubowner shared access policy that the primary key was regenerated for in the previous command:

   az iot hub connection-string show --hub-name MyExampleHub --policy-name owner --key-type primary
   

3. Use the az iot dps linked-hub list command to find the position of the IoT hub in the collection of linked IoT hubs for your DPS instance. For example, the following command gets the primary connection string for the owner shared access policy that the primary key was regenerated for in the previous command:

   az iot dps linked-hub list --dos-name MyExampleDps
   

   The output shows the position of the linked IoT hub you want to update the connection string for in the table of linked IoT hubs maintained by your DPS instance. In this case, it's the first IoT hub in the list, MyExampleHub.

   [
   {
       "allocationWeight": null,
       "applyAllocationPolicy": null,
       "connectionString": "HostName=MyExampleHub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=****",
       "location": "centralus",
       "name": "MyExampleHub.azure-devices.net"
   },
   {
       "allocationWeight": null,
       "applyAllocationPolicy": null,
       "connectionString": "HostName=MyExampleHub-2.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=****",
       "location": "centralus",
       "name": "NyExampleHub-2.azure-devices.net"
   }
   ]
   

4. Use the az iot dps update command to update the connection string for the linked IoT hub. You use the --set parameter and the position of the linked IoT hub in the properties.iotHubs[] table to target the IoT hub. For example, the following command updates the connection string for MyExampleHub returned first in the previous command:

   az iot dps update --name MyExampleDps --set properties.iotHubs[0].connectionString="HostName=MyExampleHub-2.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=NewTokenValue"
   

Next steps

• To learn more about allocation policies, see Manage allocation policies.