Erstellen und Verwalten von Rollenzuweisungen in Azure Digital Twins

Artikel
02/07/2020

Wichtig

Eine neue Version des Azure Digital Twins-Diensts wurde veröffentlicht. Angesichts der erweiterten Funktionen des neuen Diensts wurde der ursprüngliche Azure Digital Twins-Dienst (in diesem Dokumentationssatz beschrieben) eingestellt.

Um die Dokumentation für den neuen Dienst anzuzeigen, besuchen Sie die aktive Azure Digital Twins-Dokumentation.

In Azure Digital Twins wird rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) verwendet, um Zugriffe auf Ressourcen zu verwalten.

Übersicht der Rollenzuweisungen

Jede Rollenzuweisung entspricht der folgenden Definition:

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

In der folgenden Tabelle werden die einzelnen Attribute beschrieben:

attribute	Name	Erforderlich	type	Beschreibung
roleId	Bezeichner der Rollendefinition	Ja	String	Die eindeutige ID der gewünschten Rollenzuweisung. Sie können Rollendefinitionen und deren Bezeichner (IDs) durch das Abfragen der System-API ermitteln, oder die unten stehende Tabelle überprüfen.
objectId	Objektbezeichner	Ja	String	Eine Azure Active Directory-ID, eine Dienstprinzipalobjekt-ID oder ein Domänenname. Wem die Rollenzuweisung zugewiesen ist (Objekt oder Person). Die Rollenzuweisung muss gemäß ihrem zugeordneten Typ formatiert sein. Für den `DomainName`-objectIdType muss objectId mit dem `“@”`-Zeichen beginnen.
objectIdType	Objektbezeichnertyp	Ja	String	Die Art des verwendeten Objektbezeichners. Siehe unten unter Unterstützte ObjektIdTypes.
path	Raumpfad	Ja	String	Der vollständige Zugriffspfad für das `Space`-Objekt. z. B. `/{Guid}/{Guid}`. Wenn für einen Bezeichner die Rollenzuweisung für den gesamten Graphen erforderlich ist, geben Sie `"/"` an. Mit diesem Zeichen wird der Stamm angegeben, aber von der Verwendung wird abgeraten. Befolgen Sie immer das Prinzip der geringsten Rechte.
tenantId	Mandanten-ID	Varies	String	In den meisten Fällen eine Azure Active Directory-Mandanten-ID. Nicht zulässig für den `DeviceId`- und den `TenantId`-objectIdType. Erforderlich für den `UserId`- und den `ServicePrincipalId`-objectIdType. Optional für den DomainName-objectIdType.

Unterstützte Rollendefinitionsbezeichner

Jede Rollenzuweisung ordnet einer Entität in Ihrer Azure Digital Twins-Umgebung eine Rollendefinition zu.

Die folgende Tabelle beschreibt die in Azure Digital Twins verfügbaren Rollen:

Rolle	Beschreibung	Identifier
Space Administrator	ERSTELLEN-, LESEN-, AKTUALISIEREN- und LÖSCHEN-Berechtigung für den angegebenen Raum und alle Knoten darunter. Globale Berechtigung.	98e44ad7-28d4-4007-853b-b9968ad132d1
Benutzeradministrator	ERSTELLEN-, LESEN-, AKTUALISIEREN- und LÖSCHEN-Berechtigung für Benutzer und benutzerbezogene Objekte. LESEN-Berechtigung für Räume.	dfaac54c-f583-4dd2-b45d-8d4bbc0aa1ac
Device Administrator	ERSTELLEN-, LESEN-, AKTUALISIEREN- und LÖSCHEN-Berechtigung für Geräte und gerätebezogene Objekte. LESEN-Berechtigung für Räume.	3cdfde07-bc16-40d9-bed3-66d49a8f52ae
Key Administrator	ERSTELLEN, LESEN, AKTUALISIEREN und LÖSCHEN-Berechtigung für Zugriffsschlüssel. LESEN-Berechtigung für Räume.	5a0b1afc-e118-4068-969f-b50efb8e5da6
Token Administrator	ERSTELLEN- und AKTUALISIEREN-Berechtigung für Zugriffsschlüssel. LESEN-Berechtigung für Räume.	38a3bb21-5424-43b4-b0bf-78ee228840c3
Benutzer	LESEN-Berechtigung für Räume, Sensoren und Benutzer, einschließlich der dazugehörigen Objekte.	b1ffdb77-c635-4e7e-ad25-948237d85b30
Support Specialist	LESEN-Berechtigung für alle Objekte außer Zugriffsschlüsseln.	6e46958b-dc62-4e7c-990c-c3da2e030969
Device Installer	LESEN- und AKTUALISIEREN-Berechtigung für Geräte und Sensoren, einschließlich der dazugehörigen Objekte. LESEN-Berechtigung für Räume.	b16dd9fe-4efe-467b-8c8c-720e2ff8817c
Gatewaygerät	ERSTELLEN-Berechtigung für Sensoren. READ-Berechtigung für Geräte und Sensoren, die ihre entsprechenden verwandten Objekte enthalten.	d4c69766-e9bd-4e61-bfc1-d8b6e686c7a8

Unterstützte Objektbezeichnertypen

Zuvor wurde das Attribut objectIdType eingeführt.

objectIdType (oder Objektbezeichnertyp) bezieht sich auf den Typ der Identität, der einer Rolle zugewiesen wird. Mit Ausnahme der Typen DeviceId und UserDefinedFunctionId entsprechen Objektbezeichnertypen Eigenschaften von Azure Active Directory-Objekten.

Die folgende Tabelle enthält die unterstützten Objektbezeichnertypen in Azure Digital Twins:

type	BESCHREIBUNG
UserId	Weist einem Benutzer eine Rolle zu.
deviceId	Weist einem Gerät eine Rolle zu.
DomainName	Weist einem Domänennamen eine Rolle zu. Jeder Benutzer mit dem angegebenen Domänennamen hat die Zugriffsrechte der entsprechenden Rolle.
TenantId	Weist einem Mandanten eine Rolle zu. Jeder Benutzer, der zu der angegebenen Azure AD-Mandanten-ID gehört, hat die Zugriffsrechte der entsprechenden Rolle.
ServicePrincipalId	Weist einer Dienstprinzipalobjekt-ID eine Rolle zu.
UserDefinedFunctionId	Weist einer benutzerdefinierten Funktion (User-defined Function, UDF) eine Rolle zu.

Rollenzuweisungsvorgänge

Azure Digital Twins unterstützt vollständige ERSTELLEN, LESEN und LÖSCHEN-Vorgänge für Rollenzuweisungen. AKTUALISIEREN-Vorgänge werden verarbeitet, indem Rollenzuweisungen hinzugefügt oder entfernt werden oder der Knoten Raumintelligenzgraph, auf den Rollenzuweisungen Zugriff gewähren, geändert wird.

Die bereitgestellte Swagger-Referenzdokumentation enthält weitere Informationen zu allen verfügbaren API-Endpunkten, Anforderungsvorgängen und Definitionen.

Tipp

Es wird eine Swagger-Vorschau bereitgestellt, um den API-Funktionsumfang zu veranschaulichen. Diese Vorschau finden Sie unter docs.westcentralus.azuresmartspaces.net/management/swagger.

Ihre eigene generierte Dokumentation von Verwaltungs-API-Swagger finden Sie unter:

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

Name	Ersetzen durch
YOUR_INSTANCE_NAME	Den Namen Ihrer Azure Digital Twins-Instanz
YOUR_LOCATION	Die Serverregion, in der Ihre Instanz gehostet wird

In den folgenden Beispielen bezieht sich YOUR_MANAGEMENT_API_URL auf den URI der Digital Twins-APIs:

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

Name	Ersetzen durch
YOUR_INSTANCE_NAME	Den Namen Ihrer Azure Digital Twins-Instanz
YOUR_LOCATION	Die Region, in der Ihre Instanz gehostet wird

Gewähren von Berechtigungen für Ihren Dienstprinzipal

Das Gewähren von Berechtigungen für Ihren Dienstprinzipal ist häufig einer der ersten Schritte, die Sie bei der Arbeit mit Azure Digital Twins ausführen. Er umfasst:

Anmelden bei Ihrer Azure-Instanz über die Azure CLI oder PowerShell.
Abrufen Ihrer Dienstprinzipalinformationen.
Zuweisen der gewünschten Rolle zu Ihrem Dienstprinzipal.

Ihre Anwendungs-ID wird Ihnen von Azure Active Directory bereitgestellt. Weitere Informationen zum Konfigurieren und Bereitstellen eines Azure Digital Twins in Active Directory finden Sie im Schnellstart.

Nachdem Sie über die Anwendungs-ID verfügen, führen Sie einen der folgenden Befehle aus: In Azure CLI:

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

In PowerShell:

Login-AzAccount
Get-AzADServicePrincipal -ApplicationId <ApplicationId>

Ein Benutzer mit der Rolle Administrator kann einem Benutzer die Rolle „Raumadministrator“ zuweisen, indem er eine authentifizierte HTTP-POST-Anforderung an folgende URL stellt:

YOUR_MANAGEMENT_API_URL/roleassignments

Mit folgendem JSON-Text:

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

Abrufen aller Rollen

Um alle verfügbaren Rollen (Rollendefinitionen) aufzulisten, stellen Sie eine authentifizierte HTTP-GET-Anforderung an:

YOUR_MANAGEMENT_API_URL/system/roles

Eine erfolgreiche Anforderung gibt ein JSON-Array mit Einträgen für jede Rolle zurück, die zugewiesen werden kann:

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

Überprüfen einer bestimmten Rollenzuweisung

Um eine bestimmte Rollenzuweisung zu überprüfen, stellen Sie eine authentifizierte HTTP-GET-Anforderung an:

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

Parameterwert	Erforderlich	Typ	Beschreibung
YOUR_USER_ID	True	String	Die objectId für objectIdType „UserId“.
YOUR_PATH	True	String	Der ausgewählte Pfad, für den der Zugriff überprüft werden solle.
YOUR_ACCESS_TYPE	True	String	Read, Create, Update oder 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 oder UserExtendedProperty

Eine erfolgreiche Anforderung gibt einen booleschen true- oder false-Wert zurück, um anzuzeigen, ob dem Benutzer der Zugriffstyp für den angegebenen Pfad und die Ressource zugewiesen wurde.

Abrufen von Rollenzuweisungen nach Pfad

Um alle Rollenzuweisungen für einen Pfad abzurufen, stellen Sie eine authentifizierte HTTP-GET-Anforderung an:

YOUR_MANAGEMENT_API_URL/roleassignments?path=YOUR_PATH

Wert	Ersetzen durch
YOUR_PATH	Der vollständige Pfad zum Raum

Eine erfolgreiche Anforderung gibt ein JSON-Array mit jeder Rollenzuweisung zurück, die dem ausgewählten Parameter Pfad zugeordnet ist:

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

Widerrufen einer Berechtigung

Um eine Berechtigung eines Empfängers zu widerrufen, löschen Sie die Rollenzuweisung, indem Sie eine authentifizierte HTTP-DELETE-Anforderung ausführen:

YOUR_MANAGEMENT_API_URL/roleassignments/YOUR_ROLE_ASSIGNMENT_ID

Parameter	Ersetzen durch
YOUR_ROLE_ASSIGNMENT_ID	Die ID der zu entfernenden Rollenzuweisung

Eine erfolgreicher DELETE-Anforderung gibt einen Antwortstatus „204“ zurück. Überprüfen Sie das Entfernen der Rollenzuweisung, indem Sie überprüfen, ob die Rollenzuweisung noch gültig ist.

Erstellen einer Rollenzuweisung

Um eine Rollenzuweisung zu erstellen, stellen Sie eine authentifizierte HTTP-POST-Anforderung an folgende URL:

YOUR_MANAGEMENT_API_URL/roleassignments

Überprüfen Sie, ob der JSON-Text das folgende Schema einhält:

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

Eine erfolgreiche Anforderung gibt einen Antwortstatus „201“ zurück, zusammen mit der ID der neu erstellten Rollenzuweisung:

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

Konfigurationsbeispiele

Die folgenden Beispiele veranschaulichen, wie Sie Ihren JSON-Text in verschiedenen, häufig auftretenden Rollenzuweisungsszenarios konfigurieren sollten.

Beispiel: Ein Benutzer benötigt administrativen Zugriff auf einen Boden eines Mandantenraums.

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

Beispiel: Eine Anwendung führt Testszenarien aus, die Geräte und Sensoren simuliert.

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

Beispiel: Alle Benutzer, die Teil einer Domäne sind, erhalten Lesezugriff für Leerzeichen, Sensoren und Benutzer. Dieser Zugriff umfasst auch die entsprechenden zugehörigen Objekte.
```
{
  "roleId": " b1ffdb77-c635-4e7e-ad25-948237d85b30",
  "objectId" : "@microsoft.com",
  "objectIdType" : "DomainName",
  "path": "/000e349c-c0ea-43d4-93cf-6b00abd23a00"
}
```

Nächste Schritte

Informationen zum Überprüfen der rollenbasierten Zugriffssteuerung (RBAC) in Azure Digital Twins finden Sie unter Rollenbasierte Zugriffssteuerung (RBAC).
Informationen zur API-Authentifizierung in Azure Digital Twins finden Sie unter API-Authentifizierung.

Freigeben über