在 Azure 数字孪生中创建和管理角色分配

项目
02/07/2020

重要

Azure 数字孪生服务的新版本已发布。鉴于新服务的扩展功能，本文档集中介绍的原始 Azure 数字孪生服务 (已停用) 。

若要查看新服务的文档，请访问活动的 Azure 数字孪生文档。

Azure 数字孪生使用基于角色的访问控制 (RBAC) 来管理对资源的访问权限。

角色分配概述

每个角色分配符合以下定义：

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

下表描述了每个属性：

属性	名称	必须	类型	说明
roleId	角色定义标识符	是	字符串	所需角色分配的唯一 ID。通过查询系统 API 或查看下表查找角色定义及其标识符。
objectId	对象标识符	是	String	Azure Active Directory ID、服务主体对象 ID 或域名。该角色分配要分配到哪个对象。必须根据其关联类型设置角色分配的格式。对于 `DomainName` objectIdType，objectId 必须以 `“@”` 字符开头。
objectIdType	对象标识符类型	是	字符串	使用的对象标识符类型。请参阅下面的支持的 ObjectIdType。
path	空间路径	是	字符串	`Space` 对象的完整访问路径。例如 `/{Guid}/{Guid}`。如果标识符需要整个图形的角色分配，请指定 `"/"`。此字符指定根目录，但不建议使用。请始终遵循最低权限原则。
tenantId	租户标识符	多种多样	String	在大多数情况下，为 Azure Active Directory 租户 ID。不能用于 `DeviceId` 和 `TenantId` ObjectIdType。对于 `UserId` 和 `ServicePrincipalId` ObjectIdType 必需。对于 DomainName ObjectIdType 可选。

支持的角色定义标识符

每个角色分配将某个角色定义关联到 Azure 数字孪生环境中的某个实体。

下表介绍了 Azure 数字孪生中可用的角色：

角色	说明	Identifier
空间管理员	指定空间和其下所有节点的 CREATE、READ、UPDATE 和 DELETE 权限。全局权限。	98e44ad7-28d4-4007-853b-b9968ad132d1
用户管理员	用户及用户相关对象的 CREATE、READ、UPDATE 和 DELETE 权限。空间的 READ 权限。	dfaac54c-f583-4dd2-b45d-8d4bbc0aa1ac
设备管理员	设备及设备相关对象的 CREATE、READ、UPDATE 和 DELETE 权限。空间的 READ 权限。	3cdfde07-bc16-40d9-bed3-66d49a8f52ae
密钥管理员	访问密钥的 CREATE、 READ、 UPDATE 和 DELETE 权限。空间的 READ 权限。	5a0b1afc-e118-4068-969f-b50efb8e5da6
令牌管理员	访问密钥的 READ 和 UPDATE 权限。空间的 READ 权限。	38a3bb21-5424-43b4-b0bf-78ee228840c3
用户	空间、传感器和用户（包括其相应的相关对象）的 READ 权限。	b1ffdb77-c635-4e7e-ad25-948237d85b30
支持专家	除访问密钥之外的所有内容的 READ 权限。	6e46958b-dc62-4e7c-990c-c3da2e030969
设备安装员	设备和传感器（包括其相应的相关对象）的 READ 和 UPDATE 权限。空间的 READ 权限。	b16dd9fe-4efe-467b-8c8c-720e2ff8817c
网关设备	传感器的 CREATE 权限。设备和传感器的 READ 权限，其中包括相应的相关对象。	d4c69766-e9bd-4e61-bfc1-d8b6e686c7a8

支持的对象标识符类型

前面已经介绍了 objectIdType 属性。

objectIdType（或对象标识符类型）是指赋予某个角色的标识类型。除 DeviceId 和 UserDefinedFunctionId 类型外，对象标识符类型与 Azure Active Directory 对象的属性相对应。

下表包含 Azure 数字孪生中支持的对象标识符类型：

类型	说明
UserId	向用户分配角色。
DeviceId	向设备分配角色。
DomainName	向域名分配角色。具有指定域名的每位用户都将拥有相应角色的访问权限。
TenantId	向租户分配角色。属于指定 Azure AD 租户 ID 的每位用户都将拥有相应角色的访问权限。
ServicePrincipalId	向服务主体对象 ID 分配角色。
UserDefinedFunctionId	向用户定义的函数 (UDF) 分配角色。

角色分配操作

Azure 数字孪生支持对角色分配执行完整的 CREATE、READ 和 DELETE 操作。 UPDATE 操作的处理方式是添加角色分配、删除角色分配，或者修改角色分配授权访问的空间智能图形节点。

提供的 Swagger 参考文档包含了有关所有可用 API 终结点、请求操作和定义的更多信息。

提示

我们提供了 Swagger 非公开预览版来演示 API 功能集。它托管在 docs.westcentralus.azuresmartspaces.net/management/swagger 中。

可以在以下位置访问你自己的已生成管理 API Swagger 文档：

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

名称	替换为
YOUR_INSTANCE_NAME	Azure 数字孪生实例的名称
YOUR_LOCATION	托管实例的服务器区域

在以下示例中，YOUR_MANAGEMENT_API_URL 代表数字孪生 API 的 URI：

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

名称	替换为
YOUR_INSTANCE_NAME	Azure 数字孪生实例的名称
YOUR_LOCATION	托管实例的区域

向服务主体授予权限

向服务主体授予权限通常是使用 Azure 数字孪生时要执行的第一个步骤。此操作需要：

通过 Azure CLI 或 PowerShell 登录到 Azure 实例。
获取服务主体信息。
将所需的角色分配给服务主体。

应用程序 ID 在 Azure Active Directory 中提供。若要详细了解如何在 Active Directory 中配置和预配 Azure 数字孪生，请阅读快速入门。

获得应用程序 ID 后，执行以下命令之一。在 Azure CLI 中：

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

在 Powershell 中：

Login-AzAccount
Get-AzADServicePrincipal -ApplicationId <ApplicationId>

然后，具有“管理员”角色的用户可以通过向以下 URL 发出经过身份验证的 HTTP POST 请求，将“空间管理员”角色分配给用户：

YOUR_MANAGEMENT_API_URL/roleassignments

使用以下 JSON 正文：

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

检索所有角色

若要列出所有可用的角色（角色定义），请向以下对象发出经过身份验证的 HTTP GET 请求：

YOUR_MANAGEMENT_API_URL/system/roles

成功的请求将返回一个 JSON 数组，其中包含可分配的每个角色的条目：

[
    {
        "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"
    }
]

检查特定的角色分配

若要检查特定的角色分配，请向以下对象发出经过身份验证的 HTTP GET 请求：

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

参数值	必需	类型	说明
YOUR_USER_ID	True	字符串	UserId objectIdType 的 objectId。
YOUR_PATH	True	String	要检查访问权限的所选路径。
YOUR_ACCESS_TYPE	True	String	读取、创建、更新或删除
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 或 UserExtendedProperty

成功的请求将返回布尔值 true 或 false，指示是否已将该访问类型分配到给定路径和资源的用户。

按路径获取角色分配

若要检查某个路径的所有角色分配，请向以下对象发出经过身份验证的 HTTP GET 请求：

YOUR_MANAGEMENT_API_URL/roleassignments?path=YOUR_PATH

Value	替换为
YOUR_PATH	空间的完整路径

成功的请求将返回一个 JSON 数组，其中包含与所选 path 参数关联的每个角色分配：

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

撤销权限

若要从收件人撤消权限，请通过发出经过身份验证的 HTTP DELETE 请求删除角色分配：

YOUR_MANAGEMENT_API_URL/roleassignments/YOUR_ROLE_ASSIGNMENT_ID

参数	替换为
YOUR_ROLE_ASSIGNMENT_ID	要删除的角色分配的 ID

成功的 DELETE 请求将返回 204 响应状态。通过检查角色分配是否仍然存在来验证是否删除了该角色分配。

创建角色分配

若要创建角色分配，请向以下 URL 发出经过身份验证的 HTTP POST 请求：

YOUR_MANAGEMENT_API_URL/roleassignments

验证 JSON 正文是否符合以下架构：

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

成功的请求将返回 201 响应状态，以及新建的角色分配的 ID：

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

配置示例

以下示例演示如何在多种常见的角色分配方案中配置 JSON 正文。

示例：用户需要对租户空间的地板进行管理访问权限。

{
  "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"
}

示例：应用程序运行模拟设备和传感器的测试方案。

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

示例：属于域的所有用户都会收到空间、传感器和用户的读取访问权限。此访问权限包括其对应的相关对象。

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

后续步骤

若要查看 Azure 数字孪生的基于角色的访问控制，请参阅基于角色的访问控制。
若要了解 Azure 数字孪生 API 身份验证，请参阅 API 身份验证。

通过