Create and manage role assignments in Azure Digital Twins

Azure Digital Twins uses role-based access control (RBAC) to manage access to resources.

Role assignments overview

Each role assignment conforms to the following definition:

{
  "roleId": "00e00ad7-00d4-4007-853b-b9968ad000d1",
  "objectId": "be2c6daa-a3a0-0c0a-b0da-c000000fbc5f",
  "objectIdType": "ServicePrincipalId",
  "path": "/",
  "tenantId": "00f000bf-86f1-00aa-91ab-2d7cd000db47"
}

The table below describes each attribute:

Supported role definition identifiers

Each role assignment associates a role definition with an entity in your Azure Digital Twins environment.

The following table describes the roles that are available in Azure Digital Twins:

Supported object identifier types

Previously, the objectIdType attribute was introduced.

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:

Role assignment operations

Azure Digital Twins supports full CREATE, READ, and DELETE operations for role assignments. UPDATE operations are handled by adding role assignments, removing role assignments, or modifying the Spatial Intelligence Graph nodes that role assignments give access to.

The supplied Swagger reference documentation contains further information about all available API endpoints, request operations, and definitions.

You can access your own generated Management API Swagger documentation at:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

In the examples below, YOUR_MANAGEMENT_API_URL refers to the URI of the Digital Twins APIs:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

Grant permissions to your service principal

Granting permissions to your service principal is often one of the first steps you'll take when working with Azure Digital Twins. It entails:

1. Logging in to your Azure instance through Azure CLI or PowerShell.
2. Acquiring your service principal information.
3. Assigning the desired role to your service principal.

Your application ID is supplied to you in Azure Active Directory. To learn more about configuring and provisioning an Azure Digital Twins in Active Directory, read through the Quickstart.

Once you have the application ID, execute one of the following commands. In Azure CLI:

az login
az ad sp show --id <ApplicationId>

In Powershell:

Login-AzAccount
Get-AzADServicePrincipal -ApplicationId <ApplicationId>

A user with the Admin role can then assign the Space Administrator role to a user by making an authenticated HTTP POST request to the URL:

YOUR_MANAGEMENT_API_URL/roleassignments

With the following JSON body:

{
  "roleId": "98e44ad7-28d4-4007-853b-b9968ad132d1",
  "objectId": "YOUR_SERVICE_PRINCIPLE_OBJECT_ID",
  "objectIdType": "ServicePrincipalId",
  "path": "YOUR_PATH",
  "tenantId": "YOUR_TENANT_ID"
}

Retrieve all roles

To list all available roles (role definitions), make an authenticated HTTP GET request to:

YOUR_MANAGEMENT_API_URL/system/roles

A successful request will return a JSON array with entries for each role that may be assigned:

[
    {
        "id": "3cdfde07-bc16-40d9-bed3-66d49a8f52ae",
        "name": "DeviceAdministrator",
        "permissions": [
            {
                "notActions": [],
                "actions": [
                    "Read",
                    "Create",
                    "Update",
                    "Delete"
                ],
                "condition": "@Resource.Type Any_of {'Device', 'DeviceBlobMetadata', 'DeviceExtendedProperty', 'Sensor', 'SensorBlobMetadata', 'SensorExtendedProperty'} || ( @Resource.Type == 'ExtendedType' && (!Exists @Resource.Category || @Resource.Category Any_of { 'DeviceSubtype', 'DeviceType', 'DeviceBlobType', 'DeviceBlobSubtype', 'SensorBlobSubtype', 'SensorBlobType', 'SensorDataSubtype', 'SensorDataType', 'SensorDataUnitType', 'SensorPortType', 'SensorType' } ) )"
            },
            {
                "notActions": [],
                "actions": [
                    "Read"
                ],
                "condition": "@Resource.Type == 'Space' && @Resource.Category == 'WithoutSpecifiedRbacResourceTypes' || @Resource.Type Any_of {'ExtendedPropertyKey', 'SpaceExtendedProperty', 'SpaceBlobMetadata', 'SpaceResource', 'Matcher'}"
            }
        ],
        "accessControlPath": "/system",
        "friendlyPath": "/system",
        "accessControlType": "System"
    }
]

Check a specific role assignment

To check a specific role assignment, make an authenticated HTTP GET request to:

YOUR_MANAGEMENT_API_URL/roleassignments/check?userId=YOUR_USER_ID&path=YOUR_PATH&accessType=YOUR_ACCESS_TYPE&resourceType=YOUR_RESOURCE_TYPE

A successful request will return a boolean true or false to indicate whether the access type has been assigned to the user for the given path and resource.

Get role assignments by path

To get all role assignments for a path, make an authenticated HTTP GET request to:

YOUR_MANAGEMENT_API_URL/roleassignments?path=YOUR_PATH

A successful request will return a JSON array with each role assignment associated with the selected path parameter:

[
    {
        "id": "0000c484-698e-46fd-a3fd-c12aa11e53a1",
        "roleId": "98e44ad7-28d4-4007-853b-b9968ad132d1",
        "objectId": "0de38846-1aa5-000c-a46d-ea3d8ca8ee5e",
        "objectIdType": "UserId",
        "path": "/"
    }
]

Revoke a permission

To revoke a permission from a recipient, delete the role assignment by making an authenticated HTTP DELETE request:

YOUR_MANAGEMENT_API_URL/roleassignments/YOUR_ROLE_ASSIGNMENT_ID

A successful DELETE request will return a 204 response status. Verify the removal of the role assignment by checking whether the role assignment still holds.

Create a role assignment

To create a role assignment, make an authenticated HTTP POST request to the URL:

YOUR_MANAGEMENT_API_URL/roleassignments

Verify that the JSON body conforms to the following schema:

{
  "roleId": "YOUR_ROLE_ID",
  "objectId": "YOUR_OBJECT_ID",
  "objectIdType": "YOUR_OBJECT_ID_TYPE",
  "path": "YOUR_PATH",
  "tenantId": "YOUR_TENANT_ID"
}

A successful request will return a 201 response status along with the id of the newly created role assignment:

"d92c7823-6e65-41d4-aaaa-f5b32e3f01b9"

Configuration examples

The following examples demonstrate how to configure your JSON body in several commonly encountered role-assignment scenarios.

• Example: A user needs administrative access to a floor of a tenant space.

  {
    "roleId": "98e44ad7-28d4-4007-853b-b9968ad132d1",
    "objectId" : " 0fc863aa-eb51-4704-a312-7d635d70e000",
    "objectIdType" : "UserId",
    "tenantId": " a0c20ae6-e830-4c60-993d-a00ce6032724",
    "path": "/ 000e349c-c0ea-43d4-93cf-6b00abd23a44/ d84e82e6-84d5-45a4-bd9d-006a000e3bab"
  }
  

• Example: An application runs test scenarios mocking devices and sensors.

  {
    "roleId": "98e44ad7-28d4-0007-853b-b9968ad132d1",
    "objectId" : "cabf7aaa-af0b-41c5-000a-ce2f4c20000b",
    "objectIdType" : "ServicePrincipalId",
    "tenantId": " a0c20ae6-e000-4c60-993d-a91ce6000724",
    "path": "/"
  }
  

• Example: All users who are part of a domain receive read access for spaces, sensors, and users. This access includes their corresponding related objects.

  {
    "roleId": " b1ffdb77-c635-4e7e-ad25-948237d85b30",
    "objectId" : "@microsoft.com",
    "objectIdType" : "DomainName",
    "path": "/000e349c-c0ea-43d4-93cf-6b00abd23a00"
  }
  

Next steps

• To review Azure Digital Twins role-based-access-control, read Role-base-access-control.

• To learn about Azure Digital Twins API authentication, read API authentication.