Tworzenie przypisań ról i zarządzanie nimi w usłudze Azure Digital Twins

Artykuł
02/07/2020

Ważne

Wydano nową wersję usługi Azure Digital Twins. W świetle rozszerzonych możliwości nowej usługi oryginalna usługa Azure Digital Twins (opisana w tym zestawie dokumentacji) została wycofana.

Aby wyświetlić dokumentację nowej usługi, odwiedź aktywną dokumentację usługi Azure Digital Twins.

Usługa Azure Digital Twins używa kontroli dostępu opartej na rolach (RBAC) do zarządzania dostępem do zasobów.

Omówienie przypisań ról

Każde przypisanie roli jest zgodne z następującą definicją:

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

W poniższej tabeli opisano każdy atrybut:

Atrybut	Nazwa	Wymagany	Typ	Opis
roleId	Identyfikator definicji roli	Tak	Ciąg	Unikatowy identyfikator żądanego przypisania roli. Znajdź definicje ról i ich identyfikator, wysyłając zapytanie do interfejsu API systemu lub przeglądając poniższą tabelę.
objectId	Identyfikator obiektu	Tak	Ciąg	Identyfikator usługi Azure Active Directory, identyfikator obiektu jednostki usługi lub nazwa domeny. Do czego lub do kogo przypisano przypisanie roli. Przypisanie roli musi być sformatowane zgodnie z skojarzonym typem. `DomainName` Dla objectIdType, objectId musi zaczynać się od `“@”` znaku.
objectIdType	Typ identyfikatora obiektu	Tak	Ciąg	Używany rodzaj identyfikatora obiektu. Zobacz obsługiwane identyfikatory ObjectIdTypes poniżej.
path	Ścieżka spacji	Tak	Ciąg	Pełna ścieżka dostępu do `Space` obiektu. Może to być na przykład `/{Guid}/{Guid}`. Jeśli identyfikator wymaga przypisania roli dla całego grafu, określ `"/"`wartość . Ten znak wyznacza katalog główny, ale jego użycie jest zniechęcone. Zawsze przestrzegaj zasady najniższych uprawnień.
tenantId	Identyfikator dzierżawy	Różnie	Ciąg	W większości przypadków identyfikator dzierżawy usługi Azure Active Directory. Niedozwolone dla `DeviceId` i `TenantId` ObjectIdTypes. Wymagane dla `UserId` i `ServicePrincipalId` ObjectIdTypes. Opcjonalnie dla atrybutu DomainName ObjectIdType.

Obsługiwane identyfikatory definicji roli

Każde przypisanie roli kojarzy definicję roli z jednostką w środowisku usługi Azure Digital Twins.

W poniższej tabeli opisano role dostępne w usłudze Azure Digital Twins:

Role	Opis	Identyfikator
Administrator obszaru	UPRAWNIENIA CREATE, READ, UPDATE i DELETE dla określonego miejsca i wszystkich węzłów poniżej. Uprawnienia globalne.	98e44ad7-28d4-4007-853b-b9968ad132d1
Administrator użytkowników	Uprawnienia CREATE, READ, UPDATE i DELETE dla użytkowników i obiektów związanych z użytkownikami. Uprawnienie DO ODCZYTU dla spacji.	dfaac54c-f583-4dd2-b45d-8d4bbc0aa1ac
Administrator urządzenia	UPRAWNIENIA CREATE, READ, UPDATE i DELETE dla urządzeń i obiektów związanych z urządzeniami. Uprawnienie DO ODCZYTU dla spacji.	3cdfde07-bc16-40d9-bed3-66d49a8f52ae
Administrator klucza	UPRAWNIENIA CREATE, READ, UPDATE i DELETE dla kluczy dostępu. Uprawnienie DO ODCZYTU dla spacji.	5a0b1afc-e118-4068-969f-b50efb8e5da6
Administrator tokenu	Uprawnienia DO ODCZYTU i AKTUALIZACJI dla kluczy dostępu. Uprawnienie DO ODCZYTU dla spacji.	38a3bb21-5424-43b4-b0bf-78ee228840c3
Użytkownik	Uprawnienie do odczytu dla przestrzeni, czujników i użytkowników, które obejmują odpowiednie powiązane obiekty.	b1ffdb77-c635-4e7e-ad25-948237d85b30
Specjalista ds. pomocy technicznej	Uprawnienie DO ODCZYTU dla wszystkich elementów z wyjątkiem kluczy dostępu.	6e46958b-dc62-4e7c-990c-c3da2e030969
Instalator urządzenia	Uprawnienia DO ODCZYTU i AKTUALIZACJI dla urządzeń i czujników, które obejmują odpowiednie powiązane obiekty. Uprawnienie DO ODCZYTU dla spacji.	b16dd9fe-4efe-467b-8c8c-720e2ff8817c
Urządzenie bramy	Uprawnienie CREATE dla czujników. Uprawnienie do odczytu dla urządzeń i czujników, które obejmują odpowiednie powiązane obiekty.	d4c69766-e9bd-4e61-bfc1-d8b6e686c7a8

Obsługiwane typy identyfikatorów obiektów

Wcześniej wprowadzono atrybut objectIdType .

Typ objectIdType (lub typ identyfikatora obiektu) odnosi się do typu tożsamości, która jest przyznawana roli. DeviceId Oprócz typów i UserDefinedFunctionId typy typy identyfikatorów obiektów odpowiadają właściwościom obiektów usługi Azure Active Directory.

Poniższa tabela zawiera obsługiwane typy identyfikatorów obiektów w usłudze Azure Digital Twins:

Typ	Opis
UserId	Przypisuje rolę użytkownikowi.
DeviceId	Przypisuje rolę do urządzenia.
DomainName	Przypisuje rolę do nazwy domeny. Każdy użytkownik o określonej nazwie domeny ma prawa dostępu do odpowiedniej roli.
TenantId	Przypisuje rolę do dzierżawy. Każdy użytkownik należący do określonego identyfikatora dzierżawy Azure AD ma prawa dostępu odpowiadającej mu roli.
ServicePrincipalId	Przypisuje rolę do identyfikatora obiektu jednostki usługi.
UserDefinedFunctionId	Przypisuje rolę do funkcji zdefiniowanej przez użytkownika (UDF).

Operacje przypisywania ról

Usługa Azure Digital Twins obsługuje pełne operacje CREATE, READ i DELETE na potrzeby przypisań ról. Operacje AKTUALIZACJI są obsługiwane przez dodawanie przypisań ról, usuwanie przypisań ról lub modyfikowanie węzłów programu Graph analizy przestrzennej, do których przypisanie ról zapewniają dostęp.

W podanej dokumentacji referencyjnej struktury Swagger znajdują się dodatkowe informacje o wszystkich dostępnych punktach końcowych interfejsu API, operacjach żądań i definicjach.

Porada

Dostępna jest wersja zapoznawcza programu Swagger w celu zademonstrowania zestawu funkcji interfejsu API. Jest on hostowany w docs.westcentralus.azuresmartspaces.net/management/swagger.

Dostęp do własnej wygenerowanej dokumentacji programu Swagger interfejsu API zarządzania można uzyskać pod adresem:

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

Nazwa	Zamień na
YOUR_INSTANCE_NAME	Nazwa wystąpienia usługi Azure Digital Twins
YOUR_LOCATION	Region serwera, w którym jest hostowane używane wystąpienie

W poniższych YOUR_MANAGEMENT_API_URL przykładach odwołuje się do identyfikatora URI interfejsów API usługi Digital Twins:

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

Nazwa	Zamień na
YOUR_INSTANCE_NAME	Nazwa wystąpienia usługi Azure Digital Twins
YOUR_LOCATION	Region, w którym jest hostowane twoje wystąpienie

Udzielanie uprawnień jednostce usługi

Udzielanie uprawnień jednostce usługi jest często jednym z pierwszych kroków, które należy wykonać podczas pracy z usługą Azure Digital Twins. Wiąże się to z:

Logowanie się do wystąpienia platformy Azure za pomocą interfejsu wiersza polecenia platformy Azure lub programu PowerShell.
Uzyskiwanie informacji o jednostce usługi.
Przypisywanie żądanej roli do jednostki usługi.

Identyfikator aplikacji jest dostarczany w usłudze Azure Active Directory. Aby dowiedzieć się więcej na temat konfigurowania i aprowizowania usługi Azure Digital Twins w usłudze Active Directory, przeczytaj przewodnik Szybki start.

Po utworzeniu identyfikatora aplikacji wykonaj jedno z następujących poleceń. W interfejsie wiersza polecenia platformy Azure:

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

W programie PowerShell:

Login-AzAccount
Get-AzADServicePrincipal -ApplicationId <ApplicationId>

Użytkownik z rolą Administracja może następnie przypisać rolę Administrator obszaru do użytkownika, wysyłając uwierzytelnione żądanie HTTP POST do adresu URL:

YOUR_MANAGEMENT_API_URL/roleassignments

Z następującą treścią JSON:

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

Pobieranie wszystkich ról

Aby wyświetlić listę wszystkich dostępnych ról (definicji ról), wykonaj uwierzytelnione żądanie HTTP GET w celu:

YOUR_MANAGEMENT_API_URL/system/roles

Pomyślne żądanie zwróci tablicę JSON z wpisami dla każdej roli, którą można przypisać:

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

Sprawdzanie określonego przypisania roli

Aby sprawdzić określone przypisanie roli, wykonaj uwierzytelnione żądanie HTTP GET w celu:

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

Wartość parametru	Wymagane	Typ	Opis
YOUR_USER_ID	Prawda	Ciąg	ObjectId identyfikatora objectId UserIdType.
YOUR_PATH	Prawda	Ciąg	Wybrana ścieżka do sprawdzania dostępu.
YOUR_ACCESS_TYPE	Prawda	Ciąg	Odczyt, tworzenie, aktualizowanie lub usuwanie
YOUR_RESOURCE_TYPE	Prawda	Ciąg	Device, DeviceBlobMetadata, DeviceExtendedProperty, ExtendedPropertyKey, ExtendedType, Endpoint, KeyStore, Matcher, Ontology, Report, RoleDefinition, Sensor,SensorExtendedProperty, Space, SpaceBlobMetadata, SpaceExtendedProperty, SpaceExtendedProperty, SpaceResource, SpaceRoleAssignment, System, UerDefinedFunction, User, UserBlobMetadata lub UserExtendedProperty

Pomyślne żądanie zwróci wartość logiczną true lub false wskaże, czy typ dostępu został przypisany do użytkownika dla danej ścieżki i zasobu.

Pobieranie przypisań ról według ścieżki

Aby uzyskać wszystkie przypisania ról dla ścieżki, wykonaj uwierzytelnione żądanie HTTP GET w celu:

YOUR_MANAGEMENT_API_URL/roleassignments?path=YOUR_PATH

Wartość	Zamień na
YOUR_PATH	Pełna ścieżka do obszaru

Pomyślne żądanie zwróci tablicę JSON z każdym przypisaniem roli skojarzonym z wybranym parametrem ścieżki :

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

Odwoływanie uprawnienia

Aby odwołać uprawnienie od adresata, usuń przypisanie roli, wysyłając uwierzytelnione żądanie HTTP DELETE:

YOUR_MANAGEMENT_API_URL/roleassignments/YOUR_ROLE_ASSIGNMENT_ID

Parametr	Zamień na
YOUR_ROLE_ASSIGNMENT_ID	Identyfikator przypisania roli do usunięcia

Pomyślne żądanie DELETE zwróci stan odpowiedzi 204. Sprawdź usunięcie przypisania roli, sprawdzając , czy przypisanie roli nadal jest przechowywane.

Tworzenie przypisania roli

Aby utworzyć przypisanie roli, utwórz uwierzytelnione żądanie HTTP POST do adresu URL:

YOUR_MANAGEMENT_API_URL/roleassignments

Sprawdź, czy treść JSON jest zgodna z następującym schematem:

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

Pomyślne żądanie zwróci stan odpowiedzi 201 wraz z identyfikatorem nowo utworzonego przypisania roli:

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

Przykłady konfiguracji

W poniższych przykładach pokazano, jak skonfigurować treść JSON w kilku często napotykanych scenariuszach przypisywania ról.

Przykład: użytkownik musi mieć dostęp administracyjny do podłogi przestrzeni dzierżawy.

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

Przykład: Aplikacja uruchamia scenariusze testowe pozorujące urządzenia i czujniki.

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

Przykład: wszyscy użytkownicy, którzy są częścią domeny, otrzymują dostęp do odczytu dla przestrzeni, czujników i użytkowników. Ten dostęp obejmuje odpowiednie powiązane obiekty.
```
{
  "roleId": " b1ffdb77-c635-4e7e-ad25-948237d85b30",
  "objectId" : "@microsoft.com",
  "objectIdType" : "DomainName",
  "path": "/000e349c-c0ea-43d4-93cf-6b00abd23a00"
}
```

Następne kroki

Aby zapoznać się z tematem Kontrola dostępu oparta na rolach w usłudze Azure Digital Twins, przeczytaj artykuł Role-base-access-control (Kontrola dostępu oparta na rolach).
Aby dowiedzieć się więcej na temat uwierzytelniania interfejsu API usługi Azure Digital Twins, przeczytaj artykuł Uwierzytelnianie interfejsu API.

Udostępnij za pośrednictwem