Role-based access control in Azure Digital Twins

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:

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