Creare e gestire assegnazioni di ruolo in Gemelli digitali di Azure

Articolo
02/07/2020

Importante

È stata rilasciata una nuova versione del servizio Gemelli digitali di Azure. Alla luce delle funzionalità espanse del nuovo servizio, il servizio Gemelli digitali di Azure originale (descritto in questo set di documentazione) è stato ritirato.

Per visualizzare la documentazione per il nuovo servizio, vedere la documentazione attiva di Gemelli digitali di Azure.

Gemelli digitali di Azure usa il controllo degli accessi in base al ruolo per gestire l'accesso alle risorse.

Panoramica delle assegnazioni di ruolo

Ogni assegnazione di ruolo è conforme alla definizione seguente:

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

La tabella seguente descrive i singoli attributi:

Attributo	Nome	Obbligatorio	Type	Descrizione
RoleId	Identificatore della definizione di ruolo	Sì	string	ID univoco dell'assegnazione di ruolo desiderata. È possibile ottenere le definizioni dei ruoli e i relativi identificatori eseguendo una query sull'API di sistema o consultando la tabella seguente.
objectId	Identificatori di oggetto	Sì	string	ID di Azure Active Directory, ID oggetto dell'entità servizio o nome di dominio. Destinatario dell'assegnazione di ruolo. L'assegnazione di ruolo deve essere formattata in base al tipo associato. Per l'elemento objectIdType `DomainName`, objectId deve iniziare con il carattere `“@”`.
objectIdType	Tipo di identificatore di oggetto	Sì	string	Tipo di identificatore di oggetto usato. Vedere ObjectIdType supportati di seguito.
path	Percorso di spazio	Sì	string	Percorso di accesso completo dell'oggetto `Space`. Un esempio è `/{Guid}/{Guid}`. Se un identificatore richiede l'assegnazione di ruolo per l'intero grafico, specificare `"/"`. Questo carattere designa la radice, ma non è consigliabile usarlo. Seguire sempre il principio del privilegio minimo.
TenantId	Identificatore del tenant	Varia	string	Nella maggior parte dei casi, ID tenant di Azure Active Directory. Non consentito per gli elementi ObjectIdType `DeviceId` e `TenantId`. Obbligatorio per gli elementi ObjectIdType `UserId` e `ServicePrincipalId`. Facoltativo per l'elemento ObjectIdType DomainName.

Identificatori delle definizioni del ruolo supportati

Ogni assegnazione di ruolo associa una definizione del ruolo a un'entità nell'ambiente di Gemelli digitali di Azure.

La tabella seguente descrive i ruoli disponibili in Gemelli digitali di Azure:

Ruolo	Descrizione	Identificatore
Amministratore dello spazio	Autorizzazioni di CREAZIONE, LETTURA, AGGIORNAMENTO ed ELIMINAZIONE per lo spazio specificato e tutti i nodi sottostanti. Autorizzazione globale.	98e44ad7-28d4-4007-853b-b9968ad132d1
Amministratore utenti	Autorizzazioni di CREAZIONE, LETTURA, AGGIORNAMENTO ed ELIMINAZIONE per gli utenti e gli oggetti correlati agli utenti. Autorizzazione di LETTURA per gli spazi.	dfaac54c-f583-4dd2-b45d-8d4bbc0aa1ac
Amministratore del dispositivo	Autorizzazioni di CREAZIONE, LETTURA, AGGIORNAMENTO ed ELIMINAZIONE per i dispositivi e gli oggetti correlati ai dispositivi. Autorizzazione di LETTURA per gli spazi.	3cdfde07-bc16-40d9-bed3-66d49a8f52ae
Amministratore delle chiavi	Autorizzazione CREATE, READ, UPDATE e DELETE per le chiavi di accesso. Autorizzazione di LETTURA per gli spazi.	5a0b1afc-e118-4068-969f-b50efb8e5da6
Amministratore dei token	Autorizzazioni di LETTURA e AGGIORNAMENTO per le chiavi di accesso. Autorizzazione di LETTURA per gli spazi.	38a3bb21-5424-43b4-b0bf-78ee228840c3
Utente	Autorizzazione di LETTURA per gli spazi, i sensori e gli utenti, inclusi gli oggetti correlati corrispondenti.	b1ffdb77-c635-4e7e-ad25-948237d85b30
Specialista del supporto tecnico	Autorizzazione di LETTURA per tutti gli elementi ad eccezione delle chiavi di accesso.	6e46958b-dc62-4e7c-990c-c3da2e030969
Programma di installazione dei dispositivi	Autorizzazioni di LETTURA e AGGIORNAMENTO per i dispositivi e i sensori, inclusi gli oggetti correlati corrispondenti. Autorizzazione di LETTURA per gli spazi.	b16dd9fe-4efe-467b-8c8c-720e2ff8817c
Dispositivo gateway	Autorizzazione di CREAZIONE per i sensori. Autorizzazione READ per dispositivi e sensori, che include gli oggetti correlati corrispondenti.	d4c69766-e9bd-4e61-bfc1-d8b6e686c7a8

Tipi di identificatori di oggetto supportati

L'attributo objectIdType è stato presentato in precedenza.

objectIdType (o tipo di identificatore di oggetto) si riferisce al tipo di identità a cui viene assegnato un ruolo. Ad eccezione dei tipi DeviceId e UserDefinedFunctionId, i tipi di identificatore di oggetto corrispondono alle proprietà di oggetti di Azure Active Directory.

La tabella seguente elenca i tipi di identificatore di oggetto supportati in Gemelli digitali di Azure:

Type	Descrizione
UserId	Assegna un ruolo a un utente.
DeviceId	Assegna un ruolo a un dispositivo.
DomainName	Assegna un ruolo a un nome di dominio. Ogni utente con il nome di dominio specificato ha i diritti di accesso del ruolo corrispondente.
TenantId	Assegna un ruolo a un tenant. Ogni utente appartenente all'ID tenant di Azure AD specificato ha i diritti di accesso del ruolo corrispondente.
ServicePrincipalId	Assegna un ruolo a un ID oggetto entità servizio.
UserDefinedFunctionId	Assegna un ruolo a una funzione definita dall'utente.

Operazioni di assegnazione di ruolo

Gemelli digitali di Azure supporta operazioni CREATE, READ e DELETE complete per le assegnazioni di ruolo. Le operazioni UPDATE vengono gestite aggiungendo o rimuovendo assegnazioni di ruolo o modificando i nodi di Grafico di intelligenza spaziale a cui le assegnazioni di ruolo concedono l'accesso.

La documentazione di riferimento di Swagger fornita contiene ulteriori informazioni su tutti gli endpoint API, le operazioni di richiesta e le definizioni disponibili.

Suggerimento

Viene fornita un'anteprima di prova di Swagger per mostrare il set di funzionalità delle API. L'anteprima è ospitata in docs.westcentralus.azuresmartspaces.net/management/swagger.

È possibile accedere alla propria documentazione di Swagger generata automaticamente dell'API di gestione all'indirizzo:

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

NOME	Sostituire con
NOME_ISTANZA_UTENTE	Nome dell'istanza di Gemelli digitali di Azure
POSIZIONE_UTENTE	Area del server in cui è ospitata l'istanza

Negli esempi seguenti, YOUR_MANAGEMENT_API_URL fa riferimento all'URI delle API di Gemelli digitali:

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

NOME	Sostituire con
NOME_ISTANZA_UTENTE	Nome dell'istanza di Gemelli digitali di Azure
POSIZIONE_UTENTE	Area in cui è ospitata l'istanza

Concedere autorizzazioni all'entità servizio

La concessione di autorizzazioni all'entità servizio è spesso una delle prime operazioni da eseguire quando si usa Gemelli digitali di Azure. Comporta le attività seguenti:

Accesso all'istanza di Azure tramite l'interfaccia della riga di comando di Azure o PowerShell.
Acquisizione delle informazioni sull'entità servizio.
Assegnazione del ruolo desiderato all'entità servizio.

L'ID applicazione viene fornito in Azure Active Directory. Per altre informazioni sulla configurazione e il provisioning di un'istanza di Gemelli digitali di Azure in Active Directory, vedere la guida di avvio rapido.

Dopo aver ottenuto l'ID applicazione, eseguire uno dei comandi seguenti. Nell'interfaccia della riga di comando di Azure:

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

In Powershell:

Login-AzAccount
Get-AzADServicePrincipal -ApplicationId <ApplicationId>

Un utente con il ruolo Amministratore può quindi assegnare il ruolo Amministratore dello spazio a un altro utente inviando una richiesta HTTP POST autenticata all'URL:

YOUR_MANAGEMENT_API_URL/roleassignments

Con il corpo JSON seguente:

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

Recuperare tutti i ruoli

Per ottenere un elenco di tutti i ruoli disponibili (definizioni del ruolo), inviare una richiesta HTTP GET autenticata a:

YOUR_MANAGEMENT_API_URL/system/roles

Una richiesta riuscita restituirà una matrice JSON con voci per ogni ruolo che può essere assegnato:

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

Controllare un'assegnazione di ruolo specifica

Per controllare un'assegnazione di ruolo specifica, inviare una richiesta HTTP GET autenticata a:

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

Valore del parametro	Obbligatorio	Tipo	Descrizione
YOUR_USER_ID	True	string	objectId dell'objectIdType UserId.
YOUR_PATH	True	string	Percorso per cui verificare l'accesso.
YOUR_ACCESS_TYPE	True	string	Lettura, creazione, aggiornamento o eliminazione
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 o UserExtendedProperty

Una richiesta riuscita restituirà un valore booleano true o false per indicare se il tipo di accesso è stato assegnato all'utente per il percorso e la risorsa specificati.

Ottenere le assegnazioni di ruolo per percorso

Per ottenere tutte le assegnazioni di ruolo per un percorso, inviare una richiesta HTTP GET autenticata a:

YOUR_MANAGEMENT_API_URL/roleassignments?path=YOUR_PATH

Valore	Sostituire con
YOUR_PATH	Percorso completo dello spazio

Una richiesta riuscita restituirà una matrice JSON con ogni assegnazione di ruolo associata al parametro path selezionato:

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

Revocare un'autorizzazione

Per revocare un'autorizzazione a un destinatario, eliminare l'assegnazione di ruolo effettuando una richiesta HTTP DELETE autenticata:

YOUR_MANAGEMENT_API_URL/roleassignments/YOUR_ROLE_ASSIGNMENT_ID

Parametro	Sostituire con
YOUR_ROLE_ASSIGNMENT_ID	ID dell'assegnazione di ruolo da rimuovere

Una richiesta DELETE riuscita restituirà uno stato di risposta 204. Verificare la rimozione dell'assegnazione di ruolo controllando se è ancora presente.

Creare un'assegnazione di ruolo

Per creare un'assegnazione di ruolo, inviare una richiesta HTTP POST autenticata all'URL:

YOUR_MANAGEMENT_API_URL/roleassignments

Verificare che il corpo JSON sia conforme allo schema seguente:

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

Una richiesta riuscita restituirà uno stato di risposta 201 insieme all'ID dell'assegnazione di ruolo appena creata:

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

Esempi di configurazione

Gli esempi seguenti illustrano come configurare il corpo JSON in diversi scenari comuni di assegnazione di ruoli.

Esempio: un utente necessita dell'accesso amministrativo a un piano di uno spazio tenant.

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

Esempio: un'applicazione esegue scenari di test che simulano dispositivi e sensori.

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

Esempio: tutti gli utenti che fanno parte di un dominio ricevono l'accesso in lettura per spazi, sensori e utenti. inclusi gli oggetti corrispondenti correlati.

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

Passaggi successivi

Per informazioni sul controllo degli accessi in base al ruolo di Gemelli digitali di Azure, vedere Controllo degli accessi in base al ruolo.
Per altre informazioni sull'autenticazione delle API di Gemelli digitali di Azure, vedere Connettersi alle API ed eseguire l'autenticazione.

Condividi tramite