Control access to IoT Hub by using Azure Active Directory

You can use Azure Active Directory (Azure AD) to authenticate requests to Azure IoT Hub service 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 IoT Hub service APIs to an Azure AD security principal. This security principal could be a user, group, or application service principal.

Authenticating access by using Azure AD 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 Azure AD with your IoT hub whenever possible.

Note

Authentication with Azure AD isn't supported for the IoT Hub device APIs (like device-to-cloud messages and update reported properties). Use symmetric keys or X.509 to authenticate devices to IoT Hub.

Authentication and authorization

When an Azure AD security principal requests access to an IoT Hub service 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://iothubs.azure.net. 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 Azure AD principal is authenticated, the next step is authorization. In this step, IoT Hub uses the Azure AD role assignment service to determine what permissions the principal has. If the principal's permissions match the requested resource or API, IoT Hub authorizes the request. So this step requires one or more Azure roles to be assigned to the security principal. IoT Hub provides some built-in roles that have common groups of permissions.

Manage access to IoT Hub by using Azure RBAC role assignment

With Azure AD and RBAC, IoT Hub 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.

To ensure least privilege, always assign the appropriate role at the lowest possible resource scope, which is probably the IoT Hub scope.

IoT Hub provides the following Azure built-in roles for authorizing access to IoT Hub service APIs by using Azure AD and RBAC:

Role Description
IoT Hub Data Contributor Allows full access to IoT Hub data plane operations.
IoT Hub Data Reader Allows full read access to IoT Hub data plane properties.
IoT Hub Registry Contributor Allows full access to the IoT Hub device registry.
IoT Hub Twin Contributor Allows read and write access to all IoT Hub device and module twins.

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

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 IoT hub. At this scope, a role assignment applies to the IoT hub. There's no scope smaller than an individual IoT hub. Role assignment at smaller scopes, like individual device identity or twin section, 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 IoT Hub service APIs

The following table describes the permissions available for IoT Hub service 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.

RBAC action Description
Microsoft.Devices/IotHubs/devices/read Read any device or module identity.
Microsoft.Devices/IotHubs/devices/write Create or update any device or module identity.
Microsoft.Devices/IotHubs/devices/delete Delete any device or module identity.
Microsoft.Devices/IotHubs/twins/read Read any device or module twin.
Microsoft.Devices/IotHubs/twins/write Write any device or module twin.
Microsoft.Devices/IotHubs/jobs/read Return a list of jobs.
Microsoft.Devices/IotHubs/jobs/write Create or update any job.
Microsoft.Devices/IotHubs/jobs/delete Delete any job.
Microsoft.Devices/IotHubs/cloudToDeviceMessages/send/action Send a cloud-to-device message to any device.
Microsoft.Devices/IotHubs/cloudToDeviceMessages/feedback/action Receive, complete, or abandon a cloud-to-device message feedback notification.
Microsoft.Devices/IotHubs/cloudToDeviceMessages/queue/purge/action Delete all the pending commands for a device.
Microsoft.Devices/IotHubs/directMethods/invoke/action Invoke a direct method on any device or module.
Microsoft.Devices/IotHubs/fileUpload/notifications/action Receive, complete, or abandon file upload notifications.
Microsoft.Devices/IotHubs/statistics/read Read device and service statistics.
Microsoft.Devices/IotHubs/configurations/read Read device management configurations.
Microsoft.Devices/IotHubs/configurations/write Create or update device management configurations.
Microsoft.Devices/IotHubs/configurations/delete Delete any device management configuration.
Microsoft.Devices/IotHubs/configurations/applyToEdgeDevice/action Apply the configuration content to an edge device.
Microsoft.Devices/IotHubs/configurations/testQueries/action Validate the target condition and custom metric queries for a configuration.

Tip

Note

To get data from IoT Hub by using Azure AD, set up routing to a separate event hub. To access the the built-in Event Hubs compatible endpoint, use the connection string (shared access key) method as before.

Azure AD access and shared access policies

By default, IoT Hub supports service API access through both Azure AD and shared access policies and security tokens. To minimize potential security vulnerabilities inherent in security tokens, disable access with shared access policies:

  1. Ensure that your service clients and users have sufficient access to your IoT hub. Follow the principle of least privilege.
  2. In the Azure portal, go to your IoT hub.
  3. On the left pane, select Shared access policies.
  4. Under Connect using shared access policies, select Deny. Screenshot that shows how to turn off IoT Hub shared access policies.
  5. Review the warning, and then select Save.

Your IoT Hub service APIs can now be accessed only through Azure AD and RBAC.

Azure AD access from the Azure portal

When you try to access IoT Hub, the Azure portal first checks whether you've been assigned an Azure role with Microsoft.Devices/iotHubs/listkeys/action. If you have, the Azure portal uses the keys from shared access policies to access IoT Hub. If not, the Azure portal tries to access data by using your Azure AD account.

To access IoT Hub from the Azure portal by using your Azure AD account, you need permissions to access IoT Hub data resources (like devices and twins). You also need permissions to go to the IoT Hub resource in the Azure portal. The built-in roles provided by IoT Hub grant access to resources like devices and twin. But they don't grant access to the IoT Hub resource. So access to the portal also requires the assignment of an Azure Resource Manager role like Reader. The Reader role is a good choice because it's the most restricted role that lets you navigate the portal. It doesn't include the Microsoft.Devices/iotHubs/listkeys/action permission (which provides access to all IoT Hub data resources via shared access policies).

To ensure an account doesn't have access outside of the assigned permissions, don't include the Microsoft.Devices/iotHubs/listkeys/action permission when you create a custom role. For example, to create a custom role that can read device identities but can't create or delete devices, create a custom role that:

  • Has the Microsoft.Devices/IotHubs/devices/read data action.
  • Doesn't have the Microsoft.Devices/IotHubs/devices/write data action.
  • Doesn't have the Microsoft.Devices/IotHubs/devices/delete data action.
  • Doesn't have the Microsoft.Devices/iotHubs/listkeys/action action.

Then, make sure the account doesn't have any other roles that have the Microsoft.Devices/iotHubs/listkeys/action permission, like Owner or Contributor. To allow the account to have resource access and navigate the portal, assign Reader.

Azure IoT extension for Azure CLI

Most commands against IoT Hub support Azure AD 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, as before, the CLI automatically discovers a suitable policy when it interacts with IoT Hub.

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

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

SDK samples

Next steps