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.
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.
- 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 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:
|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.
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.
||Read any device or module identity.|
||Create or update any device or module identity.|
||Delete any device or module identity.|
||Read any device or module twin.|
||Write any device or module twin.|
||Return a list of jobs.|
||Create or update any job.|
||Delete any job.|
||Send a cloud-to-device message to any device.|
||Receive, complete, or abandon a cloud-to-device message feedback notification.|
||Delete all the pending commands for a device.|
||Invoke a direct method on any device or module.|
||Receive, complete, or abandon file upload notifications.|
||Read device and service statistics.|
||Read device management configurations.|
||Create or update device management configurations.|
||Delete any device management configuration.|
||Apply the configuration content to an edge device.|
||Validate the target condition and custom metric queries for a configuration.|
- The Bulk Registry Update operation requires both
- The Twin Query operation requires
- Get Digital Twin requires
Microsoft.Devices/IotHubs/twins/read. Update Digital Twin requires
- Both Invoke Component Command and Invoke Root Level Command require
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:
- Ensure that your service clients and users have sufficient access to your IoT hub. Follow the principle of least privilege.
- In the Azure portal, go to your IoT hub.
- On the left pane, select Shared access policies.
- Under Connect using shared access policies, select Deny.
- 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
- Doesn't have the
- Doesn't have the
- Doesn't have the
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
login values. The
key value is the default.
keyvalue, as before, the CLI automatically discovers a suitable policy when it interacts with IoT Hub.
loginvalue, 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.
Submit and view feedback for