Configurer une instance Azure Digital Twins et l’authentification (interface CLI)
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 :
- Création de l’instance
- 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
Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.
Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.
Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.
Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.
Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.
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 de groupe de ressources existant à l’esprit, 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 l’ID Microsoft Entra. 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 :
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 l’ID Microsoft Entra 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 est différent du rôle Propriétaire de l’ID Microsoft Entra, qui peut également être affecté à 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 vous montre comment créer une attribution de rôle pour un utilisateur dans votre instance Azure Digital Twins, à l’aide de l’e-mail de cet utilisateur dans le locataire Microsoft Entra 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 incluses avec d’autres rôles, visitez les rôles Azure, les rôles Microsoft Entra et les 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 :
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 vous oblige à transmettre le nom d’utilisateur principal sur le compte Microsoft Entra pour l’utilisateur qui doit être affecté au rôle. Dans la plupart des cas, cette valeur correspond à l’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 Portail Azure des utilisateurs de Microsoft Entra pour sélectionner le compte d’utilisateur et ouvrir ses détails. Copiez l’ID d’objet de l’utilisateur :
Répétez ensuite la commande de liste d’attributions de rôles à l’aide de l’ID d’objet de l’utilisateur pour le assignee paramètre ci-dessus.
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.
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 :