Créer et gérer des attributions de rôle dans Azure Digital Twins

Azure Digital Twins utilise le contrôle d’accès en fonction du rôle (RBAC) pour gérer l’accès aux ressources.

Vue d’ensemble des attributions de rôle

Chaque attribution de rôle est conforme à la définition suivante :

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

Le tableau suivant décrit chaque attribut :

Identificateurs de définition de rôle pris en charge

Chaque attribution de rôle associe une définition de rôle à une entité dans votre environnement Azure Digital Twins.

Le tableau suivant décrit les rôles qui sont disponibles dans Azure Digital Twins :

Types d’identificateur d’objet pris en charge

L’attribut objectIdType a été présenté précédemment.

Le objectIdType (ou le type d’identificateur d’objet) fait référence au type d’identité auquel un rôle est attribué. En dehors des types DeviceId et UserDefinedFunctionId, les types d’identificateur d’objet correspondent à des propriétés d’objets Azure Active Directory.

Le tableau suivant contient les types d’identificateurs d’objet pris en charge dans Azure Digital Twins :

Opérations d’attribution de rôle

Azure Digital Twins prend en charge les opérations CREATE, READ et DELETE pour les attributions de rôle. Les opérations UPDATE sont gérées par l’ajout d’attributions de rôle, la suppression d’attributions de rôle ou la modification des nœuds de graphique d’intelligence spatiale auxquels les attributions de rôle donnent accès.

La documentation de référence Swagger fournie contient des informations complémentaires sur tous les point de terminaison d’API disponibles, les opérations de requête et les définitions.

Vous pouvez accéder à votre propre documentation Swagger générée pour l’API Gestion à l’adresse suivante :

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

Dans les exemples ci-dessous, YOUR_MANAGEMENT_API_URL fait référence à l’URI des API Digital Twins :

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

Accorder des autorisations à votre principal de service

L’octroi d’autorisations à votre principal de service est souvent l’une des premières étapes à franchir lorsque vous utilisez Azure Digital Twins. Cela implique les opérations suivantes :

1. Connexion à votre instance Azure via Azure CLI ou PowerShell.
2. Acquisition de vos informations de principal de service.
3. Attribution du rôle souhaité à votre principal de service.

Votre ID d’application vous est attribué dans Azure Active Directory. Pour en savoir plus sur la configuration et l’approvisionnement d’Azure Digital Twins dans Active Directory, consultez le guide de Démarrage rapide.

Une fois que vous disposez de l'ID d'application, exécutez l'une des commandes suivantes. Dans Azure CLI :

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

Dans PowerShell :

Login-AzAccount
Get-AzADServicePrincipal -ApplicationId <ApplicationId>

Un utilisateur ayant le rôle Admin peut alors assigner le rôle Administrateur d’espace à un autre utilisateur en soumettant une requête HTTP POST authentifiée à l’URL :

YOUR_MANAGEMENT_API_URL/roleassignments

Avec le corps JSON suivant :

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

Récupérer tous les rôles

Pour dresser la liste de tous les rôles disponibles (définitions de rôles), exécutez une requête HTTP GET authentifiée dans :

YOUR_MANAGEMENT_API_URL/system/roles

Une requête réussie renvoie un tableau JSON répertoriant les rôles pouvant être attribués :

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

Contrôler une attribution de rôle spécifique

Pour contrôler une attribution de rôle spécifique, exécutez une requête HTTP GET authentifiée dans :

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

Une requête réussie renvoie un booléen true ou false pour indiquer si le type d’accès a été attribué à l’utilisateur pour le chemin et la ressource donnés.

Obtenir des attributions de rôle en fonction du chemin d’accès

Pour obtenir toutes les attributions de rôle pour un chemin d’accès, exécutez une requête HTTP GET authentifiée dans :

YOUR_MANAGEMENT_API_URL/roleassignments?path=YOUR_PATH

Une requête réussie renvoie un tableau JSON avec chaque attribution de rôle associée au paramètre path sélectionné :

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

Révoquer une autorisation

Pour révoquer l'autorisation d'un destinataire, supprimez l'attribution de rôle en effectuant une requête HTTP DELETE authentifiée :

YOUR_MANAGEMENT_API_URL/roleassignments/YOUR_ROLE_ASSIGNMENT_ID

Une requête de suppression réussie renvoie l’état de réponse 204. Vérifiez la suppression de l’attribution de rôle en contrôlant si l’attribution de rôle est toujours valable.

Création d'une affectation de rôle

Pour créer une attribution de rôle spécifique, exécutez une requête HTTP POST authentifiée dans l’URL :

YOUR_MANAGEMENT_API_URL/roleassignments

Vérifiez que le corps JSON est conforme au schéma suivant :

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

Une requête réussie retourne l’état de réponse 201 avec l’id de l’attribution de rôle nouvellement créée :

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

Exemples de configuration

Les exemples suivants montrent comment configurer le corps JSON dans plusieurs scénarios d’attribution de rôles couramment rencontrés.

• Exemple : un utilisateur a besoin d’un accès administratif à un étage d’un espace client.

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

• Exemple : une application exécute des scénarios de test qui fictivent des appareils et des capteurs.

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

• Exemple : tous les utilisateurs qui font partie d’un domaine reçoivent un accès en lecture pour les espaces, les capteurs et les utilisateurs. Cet accès inclut les objets connexes correspondants.

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

Étapes suivantes

• Pour passer en revue le contrôle d’accès en fonction du rôle Azure Digital Twins, lisez Contrôle d’accès en fonction du rôle.

• Pour plus d’informations sur l’authentification de l’API Azure Digital Twins, lisez Authentification des API.