Create and manage role assignments in Azure Digital Twins

Article
02/07/2020

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 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:

Attribute	Name	Required	Type	Description
roleId	Role definition identifier	Yes	String	The unique ID of the desired role assignment. Find role definitions and their identifier by querying the System API or reviewing table below.
objectId	Object identifier	Yes	String	An Azure Active Directory ID, service principal object ID, or domain name. What or whom the role assignment is assigned to. The role assignment must be formatted according to its associated type. For the `DomainName` objectIdType, objectId must begin with the `“@”` character.
objectIdType	Object identifier type	Yes	String	The kind of Object Identifier used. See Supported ObjectIdTypes below.
path	Space path	Yes	String	The full access path to the `Space` object. An example is `/{Guid}/{Guid}`. If an identifier needs the role assignment for the entire graph, specify `"/"`. This character designates the root, but its use is discouraged. Always follow the Principle of Least Privilege.
tenantId	Tenant identifier	Varies	String	In most cases, an Azure Active Directory tenant ID. Disallowed for `DeviceId` and `TenantId` ObjectIdTypes. Required for `UserId` and `ServicePrincipalId` ObjectIdTypes. Optional for the DomainName ObjectIdType.

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:

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

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:

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).

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.

Tip

A Swagger sneak preview is provided to demonstrate the API feature set. It's hosted at docs.westcentralus.azuresmartspaces.net/management/swagger.

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

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

Name	Replace with
YOUR_INSTANCE_NAME	The name of your Azure Digital Twins instance
YOUR_LOCATION	Which server region your instance is hosted on

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

Name	Replace with
YOUR_INSTANCE_NAME	The name of your Azure Digital Twins instance
YOUR_LOCATION	The region your instance is hosted on

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:

Logging in to your Azure instance through Azure CLI or PowerShell.
Acquiring your service principal information.
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

Parameter value	Required	Type	Description
YOUR_USER_ID	True	String	The objectId for the UserId objectIdType.
YOUR_PATH	True	String	The chosen path to check access for.
YOUR_ACCESS_TYPE	True	String	Read, Create, Update, or Delete
YOUR_RESOURCE_TYPE	True	String	Device, DeviceBlobMetadata, DeviceExtendedProperty, ExtendedPropertyKey, ExtendedType, Endpoint, KeyStore, Matcher, Ontology, Report, RoleDefinition, Sensor, SensorExtendedProperty, Space, SpaceBlobMetadata, SpaceExtendedProperty, SpaceResource, SpaceRoleAssignment, System, UerDefinedFunction, User, UserBlobMetadata, or UserExtendedProperty

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

Value	Replace with
YOUR_PATH	The full path to the space

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

Parameter	Replace with
YOUR_ROLE_ASSIGNMENT_ID	The id of the role assignment to remove

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.