Skapa och hantera rolltilldelningar i Azure Digital Twins

Artikel
02/07/2020

Viktigt

En ny version av Azure Digital Twins-tjänsten har släppts. Mot bakgrund av den nya tjänstens utökade funktioner har den ursprungliga Azure Digital Twins-tjänsten (som beskrivs i den här dokumentationsuppsättningen) dragits tillbaka.

Om du vill visa dokumentationen för den nya tjänsten går du till den aktiva Dokumentationen om Azure Digital Twins.

Azure Digital Twins använder rollbaserad åtkomstkontroll (RBAC) för att hantera åtkomst till resurser.

Översikt över rolltilldelningar

Varje rolltilldelning följer följande definition:

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

Tabellen nedan beskriver varje attribut:

Attribut	Name	Krävs	Typ	Beskrivning
roleId	Rolldefinitionsidentifierare	Ja	Sträng	Unikt ID för den önskade rolltilldelningen. Hitta rolldefinitioner och deras identifierare genom att fråga system-API:et eller granska tabellen nedan.
objectId	Objektidentifierare	Ja	Sträng	Ett Azure Active Directory-ID, objekt-ID för tjänstens huvudnamn eller domännamn. Vad eller vem rolltilldelningen är tilldelad till. Rolltilldelningen måste formateras enligt dess associerade typ. `DomainName` För objectIdType måste objectId börja med `“@”` tecknet.
objectIdType	Objektidentifierartyp	Ja	Sträng	Den typ av objektidentifierare som används. Se ObjectIdTypes som stöds nedan.
path	Blankstegssökväg	Ja	Sträng	Den fullständiga åtkomstsökvägen till `Space` objektet. Ett exempel är `/{Guid}/{Guid}`. Om en identifierare behöver rolltilldelningen för hela diagrammet anger du `"/"`. Det här tecknet anger roten, men dess användning rekommenderas inte. Följ alltid principen om lägsta behörighet.
tenantId	Klientidentifierare	Det varierar	Sträng	I de flesta fall ett Klient-ID för Azure Active Directory. Tillåts inte för `DeviceId` och `TenantId` ObjectIdTypes. Krävs för `UserId` och `ServicePrincipalId` ObjectIdTypes. Valfritt för DomainName ObjectIdType.

Rolldefinitionsidentifierare som stöds

Varje rolltilldelning associerar en rolldefinition med en entitet i din Azure Digital Twins-miljö.

I följande tabell beskrivs de roller som är tillgängliga i Azure Digital Twins:

Role	Beskrivning	Identifierare
Utrymmesadministratör	BEHÖRIGHETEN SKAPA, LÄSA, UPPDATERA och TA BORT för det angivna utrymmet och alla noder under. Global behörighet.	98e44ad7-28d4-4007-853b-b9968ad132d1
Användaradministratör	BEHÖRIGHETEN SKAPA, LÄSA, UPPDATERA och TA BORT för användare och användarrelaterade objekt. LÄS-behörighet för blanksteg.	dfaac54c-f583-4dd2-b45d-8d4bbc0aa1ac
Enhetsadministratör	BEHÖRIGHETEN SKAPA, LÄSA, UPPDATERA och TA BORT för enheter och enhetsrelaterade objekt. LÄS-behörighet för blanksteg.	3cdfde07-bc16-40d9-bed3-66d49a8f52ae
Nyckeladministratör	SKAPA, LÄSA, UPPDATERA och TA BORT behörighet för åtkomstnycklar. LÄS-behörighet för blanksteg.	5a0b1afc-e118-4068-969f-b50efb8e5da6
Tokenadministratör	LÄS- och UPPDATERINGsbehörighet för åtkomstnycklar. LÄS-behörighet för blanksteg.	38a3bb21-5424-43b4-b0bf-78ee228840c3
Användare	LÄS-behörighet för utrymmen, sensorer och användare, vilket inkluderar deras motsvarande relaterade objekt.	b1ffdb77-c635-4e7e-ad25-948237d85b30
Supportspecialist	LÄS-behörighet för allt utom åtkomstnycklar.	6e46958b-dc62-4e7c-990c-c3da2e030969
Installationsprogram för enhet	LÄS- och UPPDATERINGsbehörighet för enheter och sensorer, vilket inkluderar deras motsvarande relaterade objekt. LÄS-behörighet för blanksteg.	b16dd9fe-4efe-467b-8c8c-720e2ff8817c
Gateway-enhet	SKAPA-behörighet för sensorer. LÄS-behörighet för enheter och sensorer, vilket inkluderar deras motsvarande relaterade objekt.	d4c69766-e9bd-4e61-bfc1-d8b6e686c7a8

Objektidentifierartyper som stöds

Tidigare introducerades attributet objectIdType .

( objectIdType eller objektidentifierartyp) refererar till den typ av identitet som ges till en roll. Förutom typerna DeviceId och UserDefinedFunctionId motsvarar objektidentifierare egenskaper för Azure Active Directory-objekt.

Följande tabell innehåller objektidentifierartyper som stöds i Azure Digital Twins:

Typ	Beskrivning
UserId	Tilldelar en roll till en användare.
DeviceId	Tilldelar en roll till en enhet.
DomainName	Tilldelar en roll till ett domännamn. Varje användare med det angivna domännamnet har åtkomstbehörighet för motsvarande roll.
TenantId	Tilldelar en roll till en klientorganisation. Varje användare som tillhör den angivna Azure AD klientorganisations-ID har åtkomsträttigheter för motsvarande roll.
ServicePrincipalId	Tilldelar en roll till ett objekt-ID för tjänstens huvudnamn.
UserDefinedFunctionId	Tilldelar en roll till en användardefinierad funktion (UDF).

Rolltilldelningsåtgärder

Azure Digital Twins stöder fullständiga CREATE-, READ- och DELETE-åtgärder för rolltilldelningar. UPDATE-åtgärder hanteras genom att lägga till rolltilldelningar, ta bort rolltilldelningar eller ändra de Spatial Intelligence Graph-noder som rolltilldelningar ger åtkomst till.

Den angivna Swagger-referensdokumentationen innehåller ytterligare information om alla tillgängliga API-slutpunkter, begärandeåtgärder och definitioner.

Tips

En Swagger-förhandsversion tillhandahålls för att demonstrera API-funktionsuppsättningen. Den finns på docs.westcentralus.azuresmartspaces.net/management/swagger.

Du kan komma åt din egen genererade Swagger-dokumentation för hanterings-API:et på:

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

Name	Ersätt med
YOUR_INSTANCE_NAME	Namnet på din Azure Digital Twins-instans
YOUR_LOCATION	Den serverregion som instansen finns i

I exemplen nedan YOUR_MANAGEMENT_API_URL refererar till URI för Digital Twins-API:erna:

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

Name	Ersätt med
YOUR_INSTANCE_NAME	Namnet på din Azure Digital Twins-instans
YOUR_LOCATION	Den region som din instans finns på

Bevilja behörigheter till tjänstens huvudnamn

Att bevilja behörigheter till tjänstens huvudnamn är ofta ett av de första stegen du tar när du arbetar med Azure Digital Twins. Det innebär:

Logga in på din Azure-instans via Azure CLI eller PowerShell.
Hämta information om tjänstens huvudnamn.
Tilldela önskad roll till tjänstens huvudnamn.

Ditt program-ID levereras till dig i Azure Active Directory. Mer information om hur du konfigurerar och etablerar en Azure Digital Twins i Active Directory finns i snabbstarten.

När du har program-ID:t kör du något av följande kommandon. I Azure CLI:

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

I PowerShell:

Login-AzAccount
Get-AzADServicePrincipal -ApplicationId <ApplicationId>

En användare med rollen Admin kan sedan tilldela rollen Utrymmesadministratör till en användare genom att göra en autentiserad HTTP POST-begäran till URL:en:

YOUR_MANAGEMENT_API_URL/roleassignments

Med följande JSON-brödtext:

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

Hämta alla roller

Om du vill visa en lista över alla tillgängliga roller (rolldefinitioner) gör du en autentiserad HTTP GET-begäran till:

YOUR_MANAGEMENT_API_URL/system/roles

En lyckad begäran returnerar en JSON-matris med poster för varje roll som kan tilldelas:

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

Kontrollera en specifik rolltilldelning

Om du vill kontrollera en specifik rolltilldelning gör du en autentiserad HTTP GET-begäran till:

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

Parametervärde	Obligatoriskt	Typ	Beskrivning
YOUR_USER_ID	Sant	Sträng	ObjectId för UserId objectIdType.
YOUR_PATH	Sant	Sträng	Den valda sökvägen att kontrollera åtkomsten för.
YOUR_ACCESS_TYPE	Sant	Sträng	Läsa, skapa, uppdatera eller ta bort
YOUR_RESOURCE_TYPE	Sant	Sträng	Device, DeviceBlobMetadata, DeviceExtendedProperty, ExtendedPropertyKey, ExtendedType, Endpoint, KeyStore, Matcher, Ontology, Report, RoleDefinition, Sensor, SensorExtendedProperty, Space, SpaceBlobMetadata, SpaceExtendedProperty, SpaceResource, SpaceRoleAssignment, System, UerDefinedFunction, User, UserBlobMetadata eller UserExtendedProperty

En lyckad begäran returnerar ett booleskt true värde eller false anger om åtkomsttypen har tilldelats användaren för den angivna sökvägen och resursen.

Hämta rolltilldelningar efter sökväg

Om du vill hämta alla rolltilldelningar för en sökväg gör du en autentiserad HTTP GET-begäran till:

YOUR_MANAGEMENT_API_URL/roleassignments?path=YOUR_PATH

Värde	Ersätt med
YOUR_PATH	Den fullständiga sökvägen till utrymmet

En lyckad begäran returnerar en JSON-matris med varje rolltilldelning som är associerad med den valda sökvägsparametern:

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

Återkalla en behörighet

Om du vill återkalla en behörighet från en mottagare tar du bort rolltilldelningen genom att göra en autentiserad HTTP DELETE-begäran:

YOUR_MANAGEMENT_API_URL/roleassignments/YOUR_ROLE_ASSIGNMENT_ID

Parameter	Ersätt med
YOUR_ROLE_ASSIGNMENT_ID	ID för rolltilldelningen som ska tas bort

En lyckad DELETE-begäran returnerar svarsstatusen 204. Kontrollera borttagningen av rolltilldelningen genom att kontrollera om rolltilldelningen fortfarande gäller.

Skapa en rolltilldelning

Skapa en rolltilldelning genom att göra en autentiserad HTTP POST-begäran till URL:en:

YOUR_MANAGEMENT_API_URL/roleassignments

Kontrollera att JSON-brödtexten överensstämmer med följande schema:

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

En lyckad begäran returnerar svarsstatusen 201 tillsammans med ID:t för den nyligen skapade rolltilldelningen:

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

Konfigurationsexempel

Följande exempel visar hur du konfigurerar din JSON-brödtext i flera vanliga scenarier med rolltilldelning.

Exempel: En användare behöver administrativ åtkomst till en våning i ett klientutrymme.

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

Exempel: Ett program kör testscenarier som hånar enheter och sensorer.

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

Exempel: Alla användare som ingår i en domän får läsåtkomst för utrymmen, sensorer och användare. Den här åtkomsten omfattar deras motsvarande relaterade objekt.

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

Nästa steg

Om du vill granska rollbaserad åtkomstkontroll i Azure Digital Twins läser du Rollbasåtkomstkontroll.
Mer information om API-autentisering med Azure Digital Twins finns i API-autentisering.

Dela via