Zdieľať cez


Create and manage role assignments 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 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.

Role assignment endpoints

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:

  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

System 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