Role-based access control in Azure Digital Twins
Important
A new version of the Azure Digital Twins service has been released. In light of the new service's expanded capabilities, the original Azure Digital Twins service (described in this documentation set) has been retired.
To view the documentation for the new service, visit the active Azure Digital Twins Documentation.
Azure Digital Twins enables precise access control over specific data, resources, and actions in your spatial graph. It does so through granular role and permission management called role-based access control (RBAC). RBAC consists of roles and role assignments. Roles identify the level of permissions. Role assignments associate a role with a user or device.
Using RBAC, permission can be granted to:
- A user.
- A device.
- A service principal.
- A user-defined function.
- All users who belong to a domain.
- A tenant.
The degree of access can also be fine-tuned.
RBAC is unique in that permissions are inherited down the spatial graph.
What can I do with RBAC?
A developer might use RBAC to:
- Grant a user the ability to manage devices for an entire building, or only for a specific room or floor.
- Grant an administrator global access to all spatial graph nodes for an entire graph, or only for a section of the graph.
- Grant a support specialist read access to the graph, except for access keys.
- Grant every member of a domain read access to all graph objects.
RBAC best practices
Role-based access control is an inheritance-driven security strategy for managing access, permissions, and roles. Descendent roles inherit permissions from parent roles. Permissions also can be assigned without being inherited from a parent role. They also can be assigned to customize a role as needed.
For example, a Space Administrator might need global access to run all operations for a specified space. Access includes all nodes underneath or within the space. A Device Installer might need only read and update permissions for devices and sensors.
In every case, roles are granted exactly and no more than the access required to fulfill their tasks per the Principle of Least Privilege. According to this principle, an identity is granted only:
- The amount of access needed to complete its job.
- A role appropriate and limited to carrying out its job.
Important
Always follow the Principle of Least Privilege.
Two other important role-based access control practices to follow:
- Periodically audit role assignments to verify that each role has the correct permissions.
- Clean up roles and assignments when individuals change roles or assignments.
Roles
Role definitions
A role definition is a collection of permissions and other attributes that constitute a role. A role definition lists the allowed operations, which include CREATE, READ, UPDATE, and DELETE that any object with that role may perform. It also specifies to which object types the permissions apply to.
The following table describes the roles that are available in Azure Digital Twins:
| Role | Description | Identifier |
|---|---|---|
| Space Administrator | CREATE, READ, UPDATE, and DELETE permission for the specified space and all nodes underneath. Global permission. | 98e44ad7-28d4-4007-853b-b9968ad132d1 |
| User Administrator | CREATE, READ, UPDATE, and DELETE permission for users and user-related objects. READ permission for spaces. | dfaac54c-f583-4dd2-b45d-8d4bbc0aa1ac |
| Device Administrator | CREATE, READ, UPDATE, and DELETE permission for devices and device-related objects. READ permission for spaces. | 3cdfde07-bc16-40d9-bed3-66d49a8f52ae |
| Key Administrator | CREATE, READ, UPDATE, and DELETE permission for access keys. READ permission for spaces. | 5a0b1afc-e118-4068-969f-b50efb8e5da6 |
| Token Administrator | READ and UPDATE permission for access keys. READ permission for spaces. | 38a3bb21-5424-43b4-b0bf-78ee228840c3 |
| User | READ permission for spaces, sensors, and users, which includes their corresponding related objects. | b1ffdb77-c635-4e7e-ad25-948237d85b30 |
| Support Specialist | READ permission for everything except access keys. | 6e46958b-dc62-4e7c-990c-c3da2e030969 |
| Device Installer | READ and UPDATE permission for devices and sensors, which includes their corresponding related objects. READ permission for spaces. | b16dd9fe-4efe-467b-8c8c-720e2ff8817c |
| Gateway Device | CREATE permission for sensors. READ permission for devices and sensors, which includes their corresponding related objects. | d4c69766-e9bd-4e61-bfc1-d8b6e686c7a8 |
Note
To retrieve the full definitions for the previous roles, query the system/roles API. Learn more by reading Creating and managing role assignments.
Object identifier types
The objectIdType (or object identifier type) refers to the type of identity that's given to a role. Apart from the DeviceId and UserDefinedFunctionId types, object identifier types correspond to properties of Azure Active Directory objects.
The following table contains the supported object identifier types in Azure Digital Twins:
| Type | Description |
|---|---|
| UserId | Assigns a role to a user. |
| DeviceId | Assigns a role to a device. |
| DomainName | Assigns a role to a domain name. Each user with the specified domain name has the access rights of the corresponding role. |
| TenantId | Assigns a role to a tenant. Each user who belongs to the specified Azure AD tenant ID has the access rights of the corresponding role. |
| ServicePrincipalId | Assigns a role to a service principal object ID. |
| UserDefinedFunctionId | Assigns a role to a user-defined function (UDF). |
Tip
Learn how to grant permissions to your service principal by reading Creating and managing role assignments.
The following reference documentation articles describe:
- How to Query or the object ID for a user.
- How to Obtain the object ID for a service principal.
- How to Retrieve the object ID for an Azure AD tenant.
Role assignments
An Azure Digital Twins role assignment associates an object, such as a user or an Azure AD tenant, with a role and a space. Permissions are granted to all objects that belong to that space. The space includes the entire spatial graph beneath it.
For example, a user is given a role assignment with the role DeviceInstaller for the root node of a spatial graph, which represents a building. The user can then read and update devices for that node and all other child spaces in the building.
To grant permissions to a recipient, create a role assignment. To revoke permissions, remove the role assignment.
Important
Learn more about role assignments by reading Creating and managing role assignments.
Next steps
To learn more about creating and managing Azure Digital Twins role assignments, read Create and manage role assignments.
Read more about RBAC for Azure.