Azure Internet of Things built-in role
IoT Hub Twin Contributor
IoT Hub Twin Contributor reads and writes every IoT Hub device and module twin through IoT Hub service-API DataActions. It grants no Azure Resource Manager Actions, so it does not configure the IoT hub resource or create Azure role assignments.
Role-definition permissions are imported from Microsoft Learn. Practical scope, use cases, prerequisites, best practices, security considerations, assignment guidance, and relationships have been reviewed against the official sources below.
Role definition ID: 494bdba2-168f-4f31-a0a1-191d2f7c028c
Control-plane actions (0)
None — this role grants no control-plane management actions.
Data-plane actions (1)
Microsoft.Devices/IotHubs/twins/*
Excluded actions (0)
None
Assignable scopes (1)
/
Practical scope
Assign on the individual IoT hub. IoT Hub does not support a smaller Azure assignment scope for a device identity, so resource-group, subscription, or management-group assignments broaden access to every inherited hub.
Common use cases (2)
- Authorize a device-management service to read desired and reported twin state and update desired properties across one hub.
- Invoke the documented digital-twin read and update APIs that require IoT Hub twin permissions.
Prerequisites (2)
- The user, group, application, service principal, or managed identity must authenticate to the IoT Hub service API with a Microsoft Entra OAuth token; device APIs still use symmetric-key or X.509 device authentication.
- For portal access, grant Azure Reader separately so the principal can navigate to the hub without receiving list-keys access through a broad management role.
Best practices (2)
- Assign the narrowest IoT Hub data role directly on one hub and create a custom role when the client needs fewer service API operations.
- Prefer Microsoft Entra authentication for service clients and avoid roles containing listKeys; do not disable shared-access policies while linked Device Provisioning Service workflows still depend on them.
Security considerations (2)
- The role can change desired properties for every device and module twin in the hub, potentially altering device configuration or behavior.
- These roles authorize IoT Hub service APIs, not device-to-cloud device authentication and not Azure control-plane management. A parent-scope assignment affects every inherited hub.
Assignment guidance
Assign IoT Hub Twin Contributor to the service client or operator on the one IoT hub only after matching the required API operations to this role. Use a narrower built-in or custom data role when the complete published capability is unnecessary, and add Azure Reader separately only for portal navigation.
Related roles (2)
- IoT Hub Data Reader: Provides broad read access, including twin reads, without twin writes.
- IoT Hub Data Contributor: Adds device registry, jobs, messaging, direct method, configuration, and other service-API operations.
Common questions
When should I assign the IoT Hub Twin Contributor Azure role?
Assign IoT Hub Twin Contributor when you need to: Authorize a device-management service to read desired and reported twin state and update desired properties across one hub.; and Invoke the documented digital-twin read and update APIs that require IoT Hub twin permissions.. Practical scope: Assign on the individual IoT hub. IoT Hub does not support a smaller Azure assignment scope for a device identity, so resource-group, subscription, or management-group assignments broaden access to every inherited hub.
What permissions does the IoT Hub Twin Contributor Azure role grant?
The role definition grants 1 combined control-plane and data-plane actions. Representative operations include: Microsoft.Devices/IotHubs/twins/*. Review the permission sections above for the complete definition and exclusions.
What are the security risks of the IoT Hub Twin Contributor Azure role?
Key considerations when assigning IoT Hub Twin Contributor: The role can change desired properties for every device and module twin in the hub, potentially altering device configuration or behavior.; and These roles authorize IoT Hub service APIs, not device-to-cloud device authentication and not Azure control-plane management. A parent-scope assignment affects every inherited hub.. Follow the assignment guidance above and use the narrowest practical scope.
Editorial sources (6)
- Azure built-in roles for Internet of Things - Azure RBAC | Microsoft Learn →
Supports: Description, Security considerations. Retrieved 2026-07-17.
- Understand Azure role definitions →
Supports: Description, Security considerations. Retrieved 2026-07-17.
- Steps to assign an Azure role →
Supports: Assignment guidance. Retrieved 2026-07-17.
- Understand scope for Azure RBAC →
Supports: Practical scope, Assignment guidance. Retrieved 2026-07-17.
- Best practices for Azure RBAC →
Supports: Best practices, Assignment guidance. Retrieved 2026-07-17.
- Control access to IoT Hub by using Microsoft Entra ID →
Supports: Description, Practical scope, Common use cases, Prerequisites, Best practices, Security considerations, Assignment guidance, Related roles. Retrieved 2026-07-17.