在 Azure Digital Twins 中建立及管理角色指派

發行項
02/07/2020

重要

已發行新版本的 Azure Digital Twins 服務。針對新服務的擴充功能，本檔集) 中所述的原始 Azure Digital Twins 服務 (已淘汰。

若要檢視新服務的檔，請流覽使用中的 Azure Digital Twins 檔。

Azure Digital Twins 會使用角色型存取控制 (RBAC) 來管理對資源的存取。

角色指派概觀

每個角色指派符合下列定義：

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

下表描述每個屬性：

屬性	名稱	必要	類型	描述
roleId	角色定義識別碼	是	String	所需角色指派的唯一識別碼。藉由查詢系統 API 或檢閱下表，來尋找角色定義及其識別碼。
objectId	物件識別碼	是	String	Azure Active Directory 識別碼、服務主體物件識別碼或網域名稱。角色指派的指派內容以及指派給誰。角色指派必須根據其相關聯的類型進行格式化。對於 `DomainName` objectIdType，objectId 必須以 `“@”` 字元開頭。
objectIdType	物件識別碼類型	是	String	使用的物件識別項類型。請參閱以下支援的 ObjectIdTypes。
path	空間路徑	是	String	`Space` 物件的完整存取路徑。例如 `/{Guid}/{Guid}`。如果某個識別碼需要整個圖形的角色指派，請指定 `"/"`。這個字元會指定根目錄，但不鼓勵使用。一律遵循最低權限原則。
tenantId	租用戶識別碼	不一定	String	在大部分的情況下為Azure Active Directory 租用戶識別碼。不允許用於 `DeviceId` 和 `TenantId` ObjectIdTypes。必須用於 `UserId` 和 `ServicePrincipalId` ObjectIdTypes。 DomainName ObjectIdType 可選用。

支援的角色定義識別碼

每個角色指派會將角色定義與 Azure Digital Twins 環境中的實體建立關聯。

下表描述 Azure Digital Twins 中可用的角色：

角色	說明	識別碼
空間管理員	適用於指定空間及其下所有節點的建立、讀取、更新和刪除權限。全域權限。	98e44ad7-28d4-4007-853b-b9968ad132d1
使用者管理員	適用於使用者和使用者相關物件的建立、讀取、更新和刪除權限。空格的READ許可權。	dfaac54c-f583-4dd2-b45d-8d4bbc0aa1ac
裝置管理員	適用於裝置和裝置相關物件的建立、讀取、更新和刪除權限。空格的READ許可權。	3cdfde07-bc16-40d9-bed3-66d49a8f52ae
金鑰管理員	存取金鑰的 CREATE、 READ、 UPDATE和 DELETE 許可權。空格的READ許可權。	5a0b1afc-e118-4068-969f-b50efb8e5da6
權杖管理員	適用於存取金鑰的讀取和更新權限。空格的READ許可權。	38a3bb21-5424-43b4-b0bf-78ee228840c3
User	適用於空間、感應器和使用者 (包括其對應的相關物件) 的讀取權限。	b1ffdb77-c635-4e7e-ad25-948237d85b30
支援專家	存取金鑰以外各個項目的讀取權限。	6e46958b-dc62-4e7c-990c-c3da2e030969
裝置安裝人員	適用於裝置和感應器 (包括其對應的相關物件) 的讀取和更新權限。空格的READ許可權。	b16dd9fe-4efe-467b-8c8c-720e2ff8817c
閘道裝置	感應器的建立權限。裝置和感應器的READ許可權，包括其對應的相關物件。	d4c69766-e9bd-4e61-bfc1-d8b6e686c7a8

支援的物件識別碼類型

先前已介紹過 objectIdType 屬性。

objectIdType (或 物件識別碼類型) 係指給予角色的身分識別類型。除了 DeviceId 和 UserDefinedFunctionId 類型之外，物件識別碼類型還會對應至 Azure Active Directory 物件的屬性。

下表包含 Azure Digital Twins 中支援的物件識別碼類型：

類型	描述
UserId	會為使用者指派角色。
deviceId	會為裝置指派角色。
DomainName	會為網域名稱指派角色。每個具有指定網域名稱的使用者，都會有對應角色的存取權限。
TenantId	會為租用戶指派角色。每個屬於指定 Azure AD 租用戶識別碼的使用者，都會有對應角色的存取權限。
ServicePrincipalId	會為服務主體物件識別碼指派角色。
UserDefinedFunctionId	會為使用者定義函式 (UDF) 指派角色。

角色指派作業

Azure Digital Twins 對於角色指派支援完整的建立、讀取和刪除作業。更新作業的處理方法是透過新增角色指派、移除角色指派，或修改角色指派允許存取的空間智慧圖形節點。

提供的 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 Digital Twins 執行個體的名稱
YOUR_LOCATION	裝載您執行個體的伺服器區域

在以下範例中，YOUR_MANAGEMENT_API_URL 代表 Digital Twins API 的 URI：

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

名稱	更換為
YOUR_INSTANCE_NAME	Azure Digital Twins 執行個體的名稱
YOUR_LOCATION	裝載您執行個體的區域

將權限授與服務主體

將權限授與服務主體通常是使用 Azure Digital Twins 時要採取的第一步。它需要：

透過 Azure CLI 或PowerShell登入您的 Azure實例。
取得您的服務主體資訊。
將所需的角色指派給服務主體。

您的應用程式識別碼是在 Azure Active Directory 中提供的。若要深入了解在 Active Directory 中設定及佈建 Azure Digital Twins，請仔細閱讀快速入門。

一旦您擁有應用程式識別碼，請執行下列其中一個命令。在 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	String	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

值	更換為
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	要移除之角色指派的識別碼

成功的 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 回應狀態，以及新建立之角色指派的識別碼：

"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 Digital Twins 角色型存取控制，請參閱角色型存取控制。
若要深入了解 Azure Digital Twins API 驗證，請參閱 API 驗證。

共用方式為