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

次の表は、各属性を示しています。

属性	名前	必須	Type	説明
roleId	ロール定義識別子	はい	String	必要なロールの割り当ての一意 ID。ロールの定義とその識別子は、システム API のクエリを実行するか次の表を確認して見つけます。
objectId	オブジェクト識別子	はい	String	Azure Active Directory ID、サービスプリンシパルオブジェクト ID、またはドメイン名。ロールの割り当ての割り当て先。ロールの割り当ては、関連付けられている型に従って書式設定する必要があります。 `DomainName` objectIdType の場合、objectId は `“@”` 文字で始まる必要があります。
objectIdType	オブジェクト識別子の型	はい	String	使用するオブジェクト識別子の種類。下の「サポートされているオブジェクト識別子の型」をご覧ください。
path	スペースパス	はい	String	`Space` オブジェクトへの完全アクセスパス。たとえば `/{Guid}/{Guid}` です。識別子がグラフ全体のロールの割り当てを必要とする場合は、`"/"` を指定します。この文字はルートの指定ですが、これを使用することはお勧めできません。常に最小限の特権の原則に従ってください。
tenantId	テナント識別子	場合により異なる	String	ほとんどの場合、Azure Active Directory テナント ID。 `DeviceId` および `TenantId` ObjectIdTypes では許可されません。 `UserId` および `ServicePrincipalId` ObjectIdTypes では必須です。 DomainName ObjectIdType では省略可能です。

サポートされているロール定義識別子

各ロールの割り当てでは、ロールの定義が Azure Digital Twins 環境内のエンティティに関連付けられます。

次の表では、Azure Digital Twins で使用可能なロールを説明しています。

ロール	説明	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
User	スペース、センサー、ユーザー、それに対応する関連オブジェクトに対する 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 (またはオブジェクト識別子の型) は、ロールに与えられる ID の型を示します。 DeviceId および UserDefinedFunctionId 型を除き、オブジェクト識別子の型は Azure Active Directory オブジェクトのプロパティに対応します。

次の表に、Azure Digital Twins でサポートされているオブジェクト識別子の型を示します。

Type	説明
UserId	ユーザーにロールを割り当てます。
deviceId	デバイスにロールを割り当てます。
DomainName	ドメイン名にロールを割り当てます。指定されたドメイン名を持つ各ユーザーには、対応するロールのアクセス権が与えられます。
TenantId	テナントにロールを割り当てます。指定された Azure AD テナント ID に属する各ユーザーには、対応するロールのアクセス権が与えられます。
ServicePrincipalId	サービスプリンシパルのオブジェクト ID にロールを割り当てます。
UserDefinedFunctionId	ユーザー定義関数 (UDF) にロールを割り当てます。

ロールの割り当て操作

Azure Digital Twins では、ロールの割り当てに対して CREATE、READ、DELETE の操作が完全にサポートされます。 UPDATE 操作は、ロールの割り当ての追加、ロールの割り当ての削除、またはロールの割り当てによってアクセス権が付与される空間インテリジェンスグラフノードの変更によって処理されます。

提供される Swagger リファレンスドキュメントには、すべての使用可能な API エンドポイント、要求の操作、および定義に関する詳細情報が含まれています。

ヒント

API の機能を見ることができる Swagger のプレビューが提供されています。 docs.westcentralus.azuresmartspaces.net/management/swagger でホストされています。

生成された独自の Management 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 を操作するときに実行する最初の手順の 1 つです。以下を伴います。

Azure CLI または PowerShell を使用した Azure インスタンスへのログイン。
サービスプリンシパル情報の取得。
サービスプリンシパルへの必要なロールの割り当て。

Azure Active Directory 内でアプリケーション ID が提供されます。 Active Directory での Azure Digital Twins の構成とプロビジョニングについて詳しくは、クイックスタートをご覧ください。

アプリケーション 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

パラメーター値	必須	Type	説明
YOUR_USER_ID	True	String	UserId objectIdType の objectId。
YOUR_PATH	True	String	アクセスを確認する選択済みパス。
YOUR_ACCESS_TYPE	True	String	Read、Create、Update、または 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、または UserExtendedProperty

要求が成功すると、指定されたパスとリソースについてアクセスの種類がユーザーに割り当てられているかどうかを示すブール値 true または false が返されます。

パスごとのロールの割り当ての取得

1 つのパスに対するすべてのロールの割り当てを取得するには、認証済みの HTTP GET 要求を実行します。

YOUR_MANAGEMENT_API_URL/roleassignments?path=YOUR_PATH

値	置換後の文字列
YOUR_PATH	スペースへの完全パス

要求が成功すると、選択した path パラメーターに関連付けられている各ロールの割り当てを含む JSON 配列が返されます。

[
    {
        "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 Digital Twins のロールベースのアクセス制御を確認するには、ロールベースのアクセス制御に関するページをご覧ください。
Azure Digital Twins 認証について詳しくは、API 認証に関するページをご覧ください。

次の方法で共有

Azure Digital Twins 内でのロールの割り当ての作成と管理

ロールの割り当ての概要

サポートされているロール定義識別子

サポートされているオブジェクト識別子の型

ロールの割り当て操作

サービスプリンシパルにアクセス許可を付与する

すべてのロールの取得

特定のロールの割り当ての確認

パスごとのロールの割り当ての取得

アクセス許可の取り消し

ロールの割り当てを作成する

構成の例

次のステップ

その他のリソース

次の方法で共有

Azure Digital Twins 内でのロールの割り当ての作成と管理

ロールの割り当ての概要

サポートされているロール定義識別子

サポートされているオブジェクト識別子の型

ロールの割り当て操作

サービス プリンシパルにアクセス許可を付与する

すべてのロールの取得

特定のロールの割り当ての確認

パスごとのロールの割り当ての取得

アクセス許可の取り消し

ロールの割り当てを作成する

構成の例

次のステップ

その他のリソース

サービスプリンシパルにアクセス許可を付与する