Partager via

Configurer une instance Azure Digital Twins et l’authentification (interface CLI)

  • Article

Cet article explique comment configurer une nouvelle instance Azure Digital Twins, notamment la création de l’instance et la configuration de l’authentification. À l’issue de cet article, vous aurez une instance Azure Digital Twins prête pour la programmation.

La configuration complète d’une nouvelle instance Azure Digital Twins se déroule en deux phases :

  1. Création de l’instance
  2. Configuration d’autorisations d’accès utilisateur : les utilisateurs Azure doivent avoir le rôle Propriétaire de données Azure Digital Twins sur l’instance Azure Digital Twins pour pouvoir gérer celle-ci et ses données. Au cours de cette étape, en tant que Propriétaire/Administrateur de l’abonnement Azure, vous allez attribuer ce rôle à la personne qui doit gérer votre instance Azure Digital Twins. Il peut s’agir de vous-même ou d’une autre personne au sein de votre organisation.

Important

Pour terminer cet article et configurer complètement une instance utilisable, vous devez disposer des autorisations nécessaires pour gérer les ressources et l’accès utilisateur sur l’abonnement Azure. La première étape peut être effectuée par toute personne capable de créer des ressources sur l’abonnement, mais la deuxième étape nécessite des autorisations de gestion des accès utilisateur (ou la collaboration d’une personne disposant de ces autorisations). Pour en savoir plus sur l’étape concernant les autorisations d’accès utilisateur, consultez la section sur les autorisations nécessaires comme prérequis.

Prérequis

Configurer une session CLI

Pour commencer à utiliser Azure Digital Twins dans l’interface CLI, vous devez d’abord vous connecter et définir votre abonnement en tant que contexte CLI pour cette session. Exécutez les commandes suivantes dans votre fenêtre CLI :

az login
az account set --subscription "<your-Azure-subscription-ID>"

Conseil

Vous pouvez également utiliser le nom de votre abonnement à la place de l’ID dans la commande ci-dessus.

Si vous utilisez cet abonnement avec Azure Digital Twins pour la première fois, exécutez cette commande pour vous inscrire auprès de l’espace de noms Azure Digital Twins. (En cas de doute, il est possible de la réexécuter même si vous l’avez fait par le passé.)

az provider register --namespace 'Microsoft.DigitalTwins'

Vous allez ensuite ajouter l’extension Microsoft Azure IoT pour Azure CLI afin d’activer les commandes permettant d’interagir avec Azure Digital Twins et d’autres services IoT. Exécutez cette commande pour vous assurer de disposer de la version la plus récente de l’extension :

az extension add --upgrade --name azure-iot

Vous êtes maintenant prêt à utiliser Azure Digital Twins dans Azure CLI.

Vous pouvez le vérifier en exécutant az dt --help à tout moment pour voir la liste des commandes Azure Digital Twins de niveau supérieur disponibles.

Créer l’instance Azure Digital Twins

Dans cette section, vous allez créer une instance d’Azure Digital Twins à l’aide de la commande CLI. Vous devez fournir les éléments suivants :

  • Un groupe de ressources où l’instance sera déployée. Si vous n’avez pas encore choisi un groupe de ressources existant, vous pouvez en créer un maintenant avec cette commande : 
    az group create --location <region> --name <name-for-your-resource-group>
  • Une région pour le déploiement. Pour connaître les régions qui prennent en charge Azure Digital Twins, consultez Produits Azure disponibles par région.
  • Un nom pour votre instance. Si votre abonnement a une autre instance Azure Digital Twins dans la région qui utilise déjà le nom spécifié, vous êtes invité à choisir un autre nom.

Utilisez ces valeurs dans la commande az dt suivante pour créer l’instance :

az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>

Plusieurs paramètres facultatifs peuvent être ajoutés à la commande pour spécifier des éléments supplémentaires sur votre ressource lors de la création, notamment la création d’une identité managée pour l’instance ou l’activation/la désactivation de l’accès au réseau public. Pour obtenir la liste complète des paramètres pris en charge, consultez la documentation de référence d’az dt create.

Créer l’instance avec une identité managée

Lorsque vous activez une identité managée sur votre instance Azure Digital Twins, une identité est créée pour celle-ci dans Microsoft Entra ID. Cette identité peut ensuite être utilisée pour s’authentifier auprès d’autres services. Vous pouvez activer une identité managée pour une instance Azure Digital Twins lors de la création d’une instance, ou ultérieurement sur une instance existante.

Utilisez la commande CLI ci-dessous pour le type d’identité managée que vous avez choisi.

Commande d’identité affectée par le système

Pour créer une instance Azure Digital Twins avec une identité affectée par le système activée, vous pouvez ajouter un paramètre --mi-system-assigned à la commande az dt create qui est utilisée pour créer l’instance. (Pour plus d’informations sur la commande de création, consultez sa documentation de référence ou les instructions générales relatives à la configuration d’une instance d’Azure Digital Twins).

Pour créer une instance avec une identité affectée par le système, ajoutez le paramètre --mi-system-assigned comme ceci :

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned

Commande d’identité affectée par l’utilisateur

Pour créer une instance avec une identité affectée par l’utilisateur, fournissez l’ID d’une identité affectée par l’utilisateur existante à l’aide du paramètre --mi-user-assigned, comme suit :

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>

Vérifier la réussite de l’exécution et collecter les valeurs importantes

Si l’instance est correctement créée, le résultat dans l’interface CLI ressemble à ce qui suit. Vous voyez s’afficher la sortie des informations relatives à la ressource que vous avez créée :

Capture d’écran de la fenêtre Cloud Shell avec création réussie d’un groupe de ressources et d’une instance Azure Digital Twins dans le portail Azure

Notez les valeurs hostName, name et resourceGroup de l’instance Azure Digital Twins fournies dans la sortie. Ces valeurs sont toutes importantes et vous pouvez en avoir besoin quand vous continuez à travailler avec votre instance Azure Digital Twins pour configurer l’authentification et les ressources Azure associées. Si d’autres utilisateurs doivent programmer pour l’instance, vous devez partager ces valeurs avec eux.

Conseil

Vous pouvez afficher ces propriétés, ainsi que toutes les propriétés de votre instance, à tout moment en exécutant az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Vous disposez maintenant d’une instance Azure Digital Twins opérationnelle. Ensuite, vous allez accorder les autorisations utilisateur Azure appropriées pour la gérer.

Configurer les autorisations d’accès utilisateur

Azure Digital Twins utilise Microsoft Entra ID pour le contrôle d’accès en fonction du rôle (RBAC). Cela signifie qu’avant qu’un utilisateur puisse effectuer des appels de plan de données à votre instance Azure Digital Twins, il doit se voir attribuer un rôle disposant des autorisations appropriées.

Pour Azure Digital Twins, ce rôle est Propriétaire de données Azure Digital Twins. Vous pouvez en savoir plus sur les rôles et la sécurité dans Sécurité pour les solutions Azure Digital Twins.

Remarque

Ce rôle diffère du rôle Microsoft Entra ID Propriétaire qui peut également être attribué à l’étendue de l’instance Azure Digital Twins. Il s’agit de deux rôles de gestion distincts. Le rôle Propriétaire n’octroie pas d’accès aux fonctionnalités de plan de données qui sont accordées avec le rôle Propriétaire de données Azure Digital Twins.

Cette section montre comment créer une attribution de rôle pour un utilisateur dans votre instance Azure Digital Twins, en utilisant l’adresse e-mail de cet utilisateur dans le locataire Microsoft Entra ID sur votre abonnement Azure. Selon votre rôle dans votre organisation, vous pouvez configurer cette autorisation pour vous-même ou pour le compte d’une autre personne appelée à gérer l’instance Azure Digital Twins.

Configuration requise : Spécifications relatives aux autorisations

Pour être en mesure d’effectuer toutes les étapes qui suivent, vous devez disposer d’un rôle dans votre abonnement qui dispose des autorisations suivantes :

  • Créer et gérer des ressources Azure
  • Gérer l’accès des utilisateurs aux ressources Azure (y compris l’octroi et la délégation des autorisations)

Les rôles communs qui répondent à cette exigence sont Propriétaire, Administrateur de compte ou la combinaison des rôles Administrateur de l’accès utilisateur et Contributeur. Pour obtenir une explication complète des rôles et des autorisations, notamment les autorisations qui sont incluses avec d’autres rôles, consultez Rôles Azure, rôles Microsoft Entra ID et rôles d’administrateur d’abonnement classique dans la documentation Azure RBAC.

Pour consulter votre rôle dans l’abonnement, accédez à la page Abonnements du portail Azure (vous pouvez utiliser ce lien ou rechercher Abonnements dans la barre de recherche du portail). Recherchez le nom de l’abonnement que vous utilisez et affichez votre rôle dans la colonne Mon rôle :

Capture d’écran de la page Abonnements dans le portail Azure, montrant l’utilisateur en tant que propriétaire.

Si vous constatez que la valeur est Contributeurou un autre rôle qui ne dispose pas des autorisations requises décrites ci-dessus, vous pouvez contacter l’utilisateur de votre abonnement qui en dispose (par exemple, le propriétaire de l’abonnement ou l’administrateur du compte) et procéder de l’une des façons suivantes :

  • Demandez-leur d’effectuer les étapes d’attribution de rôle en votre nom.
  • Demandez qu’il élève votre rôle sur l’abonnement pour que vous disposiez des autorisations nécessaires pour continuer la procédure. Le fait que cela soit approprié dépend de votre organisation et de votre rôle au sein de celle-ci.

Attribuer le rôle

Pour accorder à un utilisateur les autorisations nécessaires pour gérer une instance Azure Digital Twins, vous devez lui attribuer le rôle Propriétaire de données Azure Digital Twins au sein de l’instance.

Utilisez la commande suivante pour attribuer le rôle (doit être exécutée par un utilisateur avec les autorisations suffisantes dans l’abonnement Azure). La commande nécessite de passer le nom d’utilisateur principal sur le compte Microsoft Entra de l’utilisateur auquel le rôle doit être attribué. Dans la plupart des cas, cette valeur correspond à l’adresse e-mail de l’utilisateur sur le compte Microsoft Entra.

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"

Les résultats de cette commande décrivent l’attribution de rôle que vous avez créée pour l’utilisateur.

Remarque

Si cette commande renvoie une erreur indiquant que l’interface CLI ne trouve pas l’utilisateur ou le principal du service dans la base de données de graphes :

Attribuez le rôle en utilisant à la place l’ID d’objet de l’utilisateur. Cela peut se produire pour les utilisateurs disposant de comptes Microsoft (MSA) personnels.

Utilisez la page du Portail Azure des utilisateurs Microsoft Entra pour sélectionner le compte d’utilisateur et ouvrir ses détails. Copiez l’ID d’objet de l’utilisateur :

Capture d’écran de la page utilisateur dans le portail Azure mettant en évidence le GUID dans le champ « ID d’objet »

Ensuite, répétez la commande « role assignment list » en utilisant l’ID d’objet de l’utilisateur pour le paramètre assignee.

Vérifier la réussite de l’exécution

Une façon de vérifier que vous avez correctement configuré l’attribution de rôle consiste à afficher les attributions de rôle pour l’instance Azure Digital Twins dans le Portail Azure. Accédez à votre instance Azure Digital Twins dans le Portail Azure. Pour cela, vous pouvez la rechercher dans la page Instances Azure Digital Twins ou rechercher son nom dans la barre de recherche du portail.

Ensuite, affichez tous les rôles qui lui sont attribués sous Contrôle d’accès (IAM) > Attributions de rôle. Votre attribution de rôle doit s’afficher dans la liste.

Capture d’écran des attributions de rôles pour une instance Azure Digital Twins dans le portail Azure

Vous disposez maintenant d’une instance Azure Digital Twins prête à l’emploi et des autorisations pour la gérer.

Activer/désactiver une identité managée pour l’instance

Cette section vous montre comment ajouter une identité managée à une instance existante d’Azure Digital Twins. Vous pouvez également désactiver l’identité managée sur une instance qui l’a déjà.

Utilisez les commandes CLI ci-dessous pour le type d’identité managée que vous avez choisi.

Commandes d’identité affectée par le système

La commande permettant d’activer l’identité affectée par le système pour une instance existante est la même commande az dt create que celle utilisée pour créer une instance avec une identité affectée par le système. Au lieu de fournir le nouveau nom pour une instance à créer, vous pouvez indiquer le nom d’une instance qui existe déjà. Ensuite, veillez à ajouter le paramètre --mi-system-assigned.

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned

Pour désactiver l’identité affectée par le système sur une instance où elle est activée, utilisez la commande suivante afin d’affecter --mi-system-assigned à la valeur false.

az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false

Commandes d’identité affectée par l’utilisateur

Pour activer une identité affectée par l’utilisateur sur une instance existante, fournissez l’ID d’une identité affectée par l’utilisateur existante dans la commande suivante :

az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

Pour désactiver une identité affectée par l’utilisateur sur une instance où elle est actuellement activée, fournissez l’ID de l’identité dans la commande suivante :

az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>

Considérations relatives à la désactivation d’identités managées

Il est important de prendre en compte les effets que toute modification apportée à l’identité ou à ses rôles peut avoir sur les ressources qui l’utilisent. Si vous utilisez des identités managées avec vos points de terminaison Azure Digital Twins ou pour l’historique des données et que l’identité est désactivée, ou si un rôle nécessaire est supprimé de celle-ci, le point de terminaison ou la connexion à l’historique des données peut devenir inaccessible et le flux d’événements sera interrompu.

Pour continuer à utiliser un point de terminaison configuré avec une identité gérée maintenant désactivée, vous devez supprimer le point de terminaison et le recréer avec un autre type d’authentification. L’opération peut prendre jusqu’à une heure avant que les événements ne soient remis au point de terminaison après cette modification.

Étapes suivantes

Testez les appels d’API REST individuels sur votre instance à l’aide des commandes CLI d’Azure Digital Twins :

Vous pouvez également découvrir comment connecter une application cliente à votre instance avec un code d’authentification :