Semion Vasilevitzky et Jonathan Elkabas

Le moyen le plus rapide de bien comprendre le fonctionnement de l'Agent ID est de le créer de bout en bout une seule fois. Ce guide pratique n'est pas destiné à servir de script à copier-coller, mais constitue plutôt un parcours guidé permettant de créer l'objet central dont nous avons parlé, afin que les flux de jetons ultérieurs soient plus faciles à comprendre.

Voici ce que vous aurez acquis à la fin des étapes de vérification pratique :

  • Un objet « Agent ID » valide défini dans votre tenant
  • Une correspondance concrète entre les chapitres théoriques et les objets « Graph » que vous pouvez énumérer
  • Une base de référence épurée que vous pouvez réutiliser pour tester les autorisations, l'héritage et la journalisation

Nous utiliserons Microsoft Graph Explorer pour les appels d'administrateur, et PowerShell 7 pour la session de configuration de l'identité de l'agent, le cas échéant. Par souci de simplicité, le compte administrateur utilisé dans cette démonstration dispose des droits d'administrateur global.

REMARQUE : l'identifiant d'agent est actuellement en préversion publique, et de nombreuses opérations décrites ci-dessous s'appuient sur des points de terminaison bêta de Microsoft Graph, qui sont susceptibles d'évoluer au fil du temps.

C'est parti.


Création d'un modèle d'identité d'agent et de son entité principale

Pour créer un modèle d'identité d'agent, vous devez fournir au minimum :

  • displayName
  • parrains (au moins un)

Envoyez une requête POST à l'adresse /applications/graph.agentIdentityBlueprint point de terminaison. (Petite mise à jour : cela peut désormais également être effectué via le centre d'administration Entra). L'entité appelante doit AgentIdentityBlueprint.Create autorisations.

Figure 1. Dénomination du modèle d'identité de l'agent

Notez l'ID de l'objet « blueprint » figurant dans la réponse. (Nous y ferons référence sous le nom de <blueprint-id>.)

Figure 2. Enregistrement de l'identifiant de l'objet « blueprint » correspondant à l'identité de l'agent

Ensuite, créez l'entité principale du modèle (l'instance d'entité de service du modèle correspondant au locataire). Envoyez une requête POST à /servicePrincipals/graph.agentIdentityBlueprintPrincipal et inclure l'ID de l'objet « blueprint » en tant que paramètre obligatoire. L'autorisation minimale requise pour cette opération est AgentIdentityBlueprintPrincipal.Create.

Figure 3. Création d'un modèle d'identité d'agent à privilèges limités

Notez l'identifiant de l'objet « blueprint principal » (entité de service) figurant dans la réponse. (Nous l'appellerons <blueprint-sp-id>.)

Figure 4. Identifiant de l'objet du directeur du projet

Ajout d'identifiants

À l'étape suivante, vous allez ajouter des informations d'identification au blueprint. Nous vous montrerons comment ajouter un certificat et un FIC ; toutefois, dans la démonstration, nous utiliserons un type d'identification « secret client », bien que cela ne soit pas recommandé (vous trouverez plus d'informations à ce sujet dans le chapitre consacré aux erreurs de configuration de ce guide).

Pour ajouter un FIC, composez le /applications//federatedIdentityCredentials avec les paramètres suivants.

Figure 5. Ajout de l'agent FIC

Pour obtenir une clé secrète client, appelez /applications//addPassword avec un passwordCredential objet (nom d'affichage + date d'expiration). Cela nécessite AgentIdentityBlueprint.AddRemoveCreds.All.

Figure 6. Obtention du secret client

Enregistrez le secretText d'après la réponse. C'est la valeur que vous utiliserez pour l'authentification ultérieure.


Authentification Blueprint

Passez à PowerShell 7 et obtenez un jeton d'accès à l'aide du secret client que vous venez de créer.

Figure 7. Obtention du jeton d'accès pour l'authentification via Blueprint

À présent, lorsque vous consulterez les journaux de connexion, vous verrez l'ID de l'entité de service « Blueprint ».

Figure 8. L'identifiant du principal de service apparaît désormais dans les journaux de connexion

Vous pouvez également consulter l'ID du modèle d'identité de l'agent dans les journaux.

Figure 9. L'identifiant du profil d'identité de l'agent dans les journaux

Maintenant que vous disposez d'un jeton d'accès pour le blueprint, vous pouvez le décoder et consulter la valeur par défaut AgentIdentity.CreateAsManager l'autorisation dont nous avons parlé tout à l'heure.

Figure 10. Affichage des autorisations du responsable de l'agent

Création de l'identité de l'agent

Le modèle étant désormais authentifié, vous pouvez l'utiliser pour créer une identité d'agent.

Pour ce faire, appelez le /servicePrincipals/Microsoft.Graph.AgentIdentity point de terminaison et fournir les propriétés suivantes : nom d'affichage, liste des sponsors et ID du modèle d'identité de l'agent.

Figure 11. Lancement de la requête d'identification de l'agent

Notez l'identifiant de l'objet d'identité de l'agent figurant dans la réponse. (Nous y ferons référence sous le nom de <agent-identity-id>.)

Figure 12. Affichage de l'ID du nouvel objet d'identité d'agent

Création d'un utilisateur agent

Avant de créer un utilisateur agent, nous avons indiqué précédemment que le modèle d'identité de l'agent devait disposer d'autorisations supplémentaires pour cette opération. Nous pouvons attribuer ces autorisations en appelant la fonction /servicePrincipals//appRoleAssignments point de terminaison et l'attribution au modèle de la AgentIdUser.ReadWrite.IdentityParentedBy Autorisation d'application. Nous utiliserons un compte d'administrateur de tenant pour effectuer cette action.

Dans le corps de la requête, nous devons inclure l'ID du SP du blueprint, l'ID de la ressource (ID du SP MS Graph) et l'ID du rôle de l'application, que vous trouverez ici.

Figure 13. Attribution d'autorisations au modèle d'identité de l'agent

Nous pouvons désormais créer un utilisateur agent. Après avoir obtenu un nouveau jeton pour le blueprint en utilisant la même méthode que celle que vous avez déjà employée, vous pouvez constater que le rôle nouvellement attribué apparaît bien dans le jeton du blueprint.

Figure 14. Affichage du rôle de gestionnaire nouvellement créé dans notre nouveau jeton

Nous pouvons désormais utiliser ce jeton pour créer un utilisateur-agent en appelant la fonction /users/microsoft.graph.agentUser le point de terminaison et en fournissant un nom d'affichage, un nom principal d'utilisateur, un pseudonyme de messagerie, l'identifiant d'identité de l'agent en tant que parent de l'utilisateur de l'agent, et enfin un indicateur précisant si le compte est activé ou désactivé.

Figure 15. Saisie des informations relatives au nouvel utilisateur agent

Notez l'identifiant de l'objet utilisateur de l'agent figurant dans la réponse. (Nous y ferons référence sous le nom de <agent-user-id>.)

Figure 16. Réception de l'identifiant de l'objet utilisateur de l'agent

Rappel : chaque identité d'agent ne peut avoir qu'un seul utilisateur d'agent en tant qu'enfant (relation 1:1).

Félicitations ! Vous avez créé une identité d'agent.

Dans le chapitre suivant de notre guide, nous approfondirons la conception des attributs de l'identité de l'agent.


Découvrez le guide