Control access to Azure IoT Hub Device Provisioning Service (DPS) by using Microsoft Entra ID (preview)

You can use Microsoft Entra ID to authenticate requests to Azure IoT Hub Device Provisioning Service (DPS) APIs, like create device identity and invoke direct method. You can also use Azure role-based access control (Azure RBAC) to authorize those same service APIs. By using these technologies together, you can grant permissions to access Azure IoT Hub Device Provisioning Service (DPS) APIs to a Microsoft Entra security principal. This security principal could be a user, group, or application service principal.

Authenticating access by using Microsoft Entra ID and controlling permissions by using Azure RBAC provides improved security and ease of use over security tokens. To minimize potential security issues inherent in security tokens, we recommend that you use Microsoft Entra ID with your Azure IoT Hub Device Provisioning Service (DPS) whenever possible.

Authentication and authorization

When a Microsoft Entra security principal requests access to an Azure IoT Hub Device Provisioning Service (DPS) API, the principal's identity is first authenticated. For authentication, the request needs to contain an OAuth 2.0 access token at runtime. The resource name for requesting the token is https://azure-devices-provisioning.cn. If the application runs in an Azure resource like an Azure VM, Azure Functions app, or Azure App Service app, it can be represented as a managed identity.

After the Microsoft Entra principal is authenticated, the next step is authorization. In this step, Azure IoT Hub Device Provisioning Service (DPS) uses the Microsoft Entra role assignment service to determine what permissions the principal has. If the principal's permissions match the requested resource or API, Azure IoT Hub Device Provisioning Service (DPS) authorizes the request. So this step requires one or more Azure roles to be assigned to the security principal. Azure IoT Hub Device Provisioning Service (DPS) provides some built-in roles that have common groups of permissions.

Manage access to Azure IoT Hub Device Provisioning Service (DPS) by using Azure RBAC role assignment

With Microsoft Entra ID and RBAC, Azure IoT Hub Device Provisioning Service (DPS) requires the principal requesting the API to have the appropriate level of permission for authorization. To give the principal the permission, give it a role assignment.

• If the principal is a user, group, or application service principal, follow the guidance in Assign Azure roles by using the Azure portal.
• If the principal is a managed identity, follow the guidance in Assign a managed identity access to a resource by using the Azure portal.

To ensure least privilege, always assign the appropriate role at the lowest possible resource scope, which is probably the Azure IoT Hub Device Provisioning Service (DPS) scope.

Azure IoT Hub Device Provisioning Service (DPS) provides the following Azure built-in roles for authorizing access to DPS APIs by using Microsoft Entra ID and RBAC:

You can also define custom roles to use with Azure IoT Hub Device Provisioning Service (DPS) by combining the permissions that you need. For more information, see Create custom roles for Azure role-based access control.

Control-plane write and shared access policy keys

The Microsoft.Devices/provisioningServices/write action lets a principal create or update any property of the DPS resource, including the authorizationPolicies collection. Because the Azure Resource Manager (ARM) contract for CreateOrUpdate accepts caller-supplied primaryKey and secondaryKey values on each policy, a principal that holds write on a DPS resource can:

• Set the primary or secondary key of any shared access policy (including the root provisioningserviceowner policy) to a value they choose, and then authenticate as that policy.
• Rotate the keys of any shared access policy, which invalidates existing consumers.
• Add a new named shared access policy with a chosen key value.

For this reason, Microsoft.Devices/provisioningServices/write is functionally equivalent to full administration of the resource's shared access policy credentials, regardless of whether the principal also holds Microsoft.Devices/provisioningServices/listkeys/action or Microsoft.Devices/provisioningServices/listkey/action.

If you need to separate resource configuration from shared access policy credential administration, use one of the following patterns instead:

• Prefer Microsoft Entra ID authentication for the data plane. Assign the built-in Device Provisioning Service Data Contributor or Device Provisioning Service Data Reader roles for enrollment management, and disable shared-access-signature access on the resource where possible.
• Restrict write at the resource scope. Because write implies key control, grant it only to principals that you trust with shared access policy credentials.
• Audit control-plane activity. Changes to authorizationPolicies made through the control-plane PUT are recorded in the Azure Activity Log under the Microsoft.Devices/provisioningServices/write operation. Review these events alongside listkeys/action events when auditing credential access.

The same considerations apply to Azure IoT Hub. For details, see Control access to IoT Hub by using Microsoft Entra ID.

Resource scope

Before you assign an Azure RBAC role to a security principal, determine the scope of access that the security principal should have. It's always best to grant only the narrowest possible scope. Azure RBAC roles defined at a broader scope are inherited by the resources beneath them.

This list describes the levels at which you can scope access to IoT Hub, starting with the narrowest scope:

• The Azure IoT Hub Device Provisioning Service (DPS). At this scope, a role assignment applies to the Azure IoT Hub Device Provisioning Service (DPS). Role assignment at smaller scopes, like enrollment group or individual enrollment, isn't supported.
• The resource group. At this scope, a role assignment applies to all IoT hubs in the resource group.
• The subscription. At this scope, a role assignment applies to all IoT hubs in all resource groups in the subscription.
• A management group. At this scope, a role assignment applies to all IoT hubs in all resource groups in all subscriptions in the management group.

Permissions for Azure IoT Hub Device Provisioning Service (DPS) APIs

The following table describes the permissions available for Azure IoT Hub Device Provisioning Service (DPS) API operations. To enable a client to call a particular operation, ensure that the client's assigned RBAC role offers sufficient permissions for the operation.

Azure IoT extension for Azure CLI

Most commands against Azure IoT Hub Device Provisioning Service (DPS) support Microsoft Entra authentication. You can control the type of authentication used to run commands by using the --auth-type parameter, which accepts key or login values. The key value is the default.

• When --auth-type has the key value, the CLI automatically discovers a suitable policy when it interacts with Azure IoT Hub Device Provisioning Service (DPS).

• When --auth-type has the login value, an access token from the Azure CLI logged in the principal is used for the operation.

• The following commands currently support --auth-type:

  • az iot dps enrollment
  • az iot dps enrollment-group
  • az iot dps registration

For more information, see the Azure IoT extension for Azure CLI release page.

SDKs and samples

• Azure IoT SDKs for Node.js Provisioning Service
  • Sample
• Azure IoT SDK for Java Preview Release
  • Sample
• Azure IoT SDKs for .NET Preview Release

Microsoft Entra ID access from the Azure portal

Next steps

• For more information on the advantages of using Microsoft Entra ID in your application, see Integrating with Microsoft Entra ID.
• For more information on requesting access tokens from Microsoft Entra ID for users and service principals, see Authentication scenarios for Microsoft Entra ID.