Enregistrement personnalisé de l’application client pour l’Agent 365 CLI

L’interface en ligne de commande Agent 365 a besoin d’une inscription d’application cliente personnalisée dans votre locataire Microsoft Entra ID pour authentifier et gérer les Blueprints d’identité de l’agent.

Cet article décompose le processus en quatre étapes principales :

1. Demande de registre
2. Définir l’URI de Redirection
3. Copie de l’ID de l’application (client)
4. Configurer les autorisations d’API

Si vous avez des problèmes, consultez la section Dépannage .

Prerequisites

Avant de commencer, vérifiez que vous avez accès à Microsoft Entra centre d’administration et, si nécessaire, l’un des rôles d’administrateur requis pour accorder le consentement.

Pour enregistrer l’application

Par défaut, tout utilisateur du locataire peut enregistrer des applications dans le centre d’administration Microsoft Entra. Cependant, les administrateurs de locataires peuvent restreindre cette capacité. Si vous ne pouvez pas enregistrer votre application, contactez votre administrateur.

Ajouter des autorisations et accorder le consentement

Vous avez besoin d’un de ces rôles administratifs pour 4. Configurez les permissions de l’API.

• Administrateur d'application : recommandé - peut gérer les enregistrements d'applications et accorder son consentement
• Administrateur d’applications cloud : Peut gérer les inscriptions d’applications et accorder le consentement
• Administrateur global : Dispose de toutes les permissions, mais non requis

1. Inscription de la demande

Ces instructions résument toutes les instructions pour créer une inscription à une application.

1. Accédez au centre d’administration Microsoft Entra

2. Sélectionnez Enregistrements d'applications

3. Sélectionnez Nouvelle inscription

4. Entrez :

   • Nom : Saisissez un nom significatif pour votre application, tel que my-agent-app. Les utilisateurs de l’application voient ce nom et vous pouvez le modifier à tout moment. Vous pouvez avoir plusieurs inscriptions d’applications portant le même nom.
   • Types de comptes pris en charge : comptes dans ce répertoire organisationnel uniquement (locataire unique)
   • Redirection URI : sélectionnez Client public/natif (mobile & bureau) et entrez http://localhost:8400/

5. Sélectionnez Inscrire.

2. Définir l’URI de redirection

1. Allez dans Aperçu et copiez la valeur ID de l’application (client ).
2. Allez dans Authentification (aperçu) et sélectionnez Ajouter une URI de redirection.
3. Sélectionnez Applications mobiles et de bureau et définissez la valeur à ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, où {client-id} est la valeur de l’application (identifiant client) que vous avez copiée.
4. Sélectionnez Configurer pour ajouter la valeur.

3. Copie de l’ID de l’application (client)

Depuis la page d’aperçu de l’application, copiez l’ID de l’application (client) au format GUID. Saisissez cette valeur lorsque vous utilisez la a365 config init commande.

4. Configurer les permissions de l’API

Choisissez la méthode appropriée :

• Option A : utilisez Microsoft Entra centre d’administration pour toutes les autorisations (si les autorisations bêta sont visibles)
• Option B : utilisez Microsoft Graph API pour ajouter toutes les autorisations (recommandé si les autorisations bêta ne sont pas visibles)

Option A : Microsoft Entra centre d’administration (méthode standard)

Utilisez cette méthode si les autorisations en version bêta sont visibles dans votre espace client.

1. Dans l’inscription de votre application, accédez aux autorisations d’API.

2. Sélectionnez Ajouter une autorisation>Microsoft Graph>Autorisations déléguées.

   Important

   Vous DEVEZ utiliser les permissions déléguées (PAS les permissions d’application). Le CLI s’authentifie de manière interactive – vous vous connectez, et il agit en votre nom. Voir « Mauvais type d’autorisation » si vous ajoutez accidentellement des permissions d’application.

3. Ajoutez ces cinq permissions une par une :

   Autorisation	Objectif
   AgentIdentityBlueprint.ReadWrite.All	Gérer les configurations Agent Blueprint (API bêta)
   AgentIdentityBlueprint.UpdateAuthProperties.All	Mettre à jour les permissions héréditaires de l’agent Blueprint (API bêta)
   Application.ReadWrite.All	Créer et gérer des applications et des modèles d’agent
   DelegatedPermissionGrant.ReadWrite.All	Accorder des autorisations pour les plans des agents
   Directory.Read.All	Lire les données du répertoire pour validation

   Pour chaque autorisation :

   • Dans la barre de recherche, tapez le nom de l’autorisation (par exemple, AgentIdentityBlueprint.ReadWrite.All).
   • Cochez la case à cocher à côté de l’autorisation.
   • Sélectionnez Ajouter des autorisations.
   • Répétez pour les cinq autorisations.

4. Sélectionnez Accorder le consentement administrateur pour [Votre locataire].

   • Pourquoi est-ce nécessaire ? Les plans d’identité d’agent sont des ressources à l’échelle du locataire auxquelles plusieurs utilisateurs et applications peuvent se référer. Sans le consentement de l’ensemble du locataire, la CLI échoue lors de l’authentification.
   • Et si ça échoue ? Vous avez besoin d’un rôle d’Administrateur d’Applications, d’Administrateur d’Application Cloud ou d’Administrateur Global. Demandez de l’aide à votre administrateur locataire.

5. Vérifiez que toutes les autorisations affichent des coches vertes sous Statut.

Si les autorisations bêta (AgentIdentityBlueprint.*) ne sont pas visibles, passez à l’option B.

Option B : Microsoft Graph API (pour les autorisations bêta)

Utilisez cette méthode si AgentIdentityBlueprint.* les autorisations ne sont pas visibles dans le centre d'administration Microsoft Entra.

1. Ouvrez Graph Explorer.

2. Connectez-vous avec votre compte administrateur (Administrateur d’application ou Administrateur d’application cloud).

3. Accordez le consentement de l’administrateur à l’aide de Graph API. Pour effectuer cette étape, vous avez besoin des éléments suivants :

   • ID de principal de service Il vous faut une SP_OBJECT_ID valeur variable.
   • ID de ressource du graphe. Il vous faut une GRAPH_RESOURCE_ID valeur variable.
   • Créer (ou mettre à jour) les permissions déléguées en utilisant le type de ressource oAuth2PermissionGrant avec les valeurs des variables SP_OBJECT_ID et GRAPH_RESOURCE_ID.

Utilisez les informations des sections suivantes pour compléter ces étapes.

Obtenez votre identifiant de service principal

Un principal de service est l’identité de votre application dans votre locataire. Vous en avez besoin avant de pouvoir accorder des autorisations via l’API.

1. Configurez la méthode Graph Explorer sur GET et utilisez cette URL. Remplacez <YOUR_CLIENT_APP_ID> par votre véritable ID client Application à l’étape 3 : Copiez l’ID Application (client) :

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id
   

2. Sélectionnez Exécuter la requête.

   • Si la requête réussit, la valeur retournée est votre SP_OBJECT_ID.

   • Si la requête échoue avec une erreur de permissions, sélectionnez l’onglet Modifier les permissions , consentez aux autorisations requises, puis sélectionnez à nouveau Exécuter la requête . La valeur retournée est votre SP_OBJECT_ID.

   • Si la requête retourne des résultats vides ("value": []), créez le principal de service en suivant les étapes suivantes :

     1. Définir la méthode pour POST et utiliser cette URL :

        https://graph.microsoft.com/v1.0/servicePrincipals
        

        Corps de demande (remplacez YOUR_CLIENT_APP_ID par l’identifiant client de votre application) :

        {
           "appId": "YOUR_CLIENT_APP_ID"
        }
        

     2. Sélectionnez Exécuter la requête. Vous devriez recevoir une 201 Created réponse. La id valeur retournée est votre SP_OBJECT_ID.

Obtenez votre identifiant de ressource Graph

1. Réglez la méthode Graph Explorer sur GET et utilisez cette URL :

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id
   

2. Sélectionnez Exécuter la requête.

   • Si la requête réussit, copiez la id valeur. Cette valeur est votre GRAPH_RESOURCE_ID.
   • Si la requête échoue avec une erreur de permissions, sélectionnez l’onglet Modifier les permissions , consentez aux autorisations requises, puis sélectionnez à nouveau Exécuter la requête . Copiez la valeur de id. Cette valeur est votre GRAPH_RESOURCE_ID.

Créer des permissions déléguées

Cet appel d'API accorde le consentement administrateur à l'échelle du locataire pour les cinq autorisations, y compris les deux autorisations bêta qui ne sont pas visibles dans le centre d'administration Microsoft Entra.

1. Réglez la méthode Graph Explorer sur POST et utilisez cette URL ainsi que le corps de la requête :

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants
   

   Corps de la demande :

   {
   "clientId": "<SP_OBJECT_ID>",
   "consentType": "AllPrincipals",
   "principalId": null,
   "resourceId": "<GRAPH_RESOURCE_ID>",
   "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

2. Sélectionnez Exécuter la requête.

   • Si vous obtenez 201 Created une réponse : Succès ! Le scope champ dans la réponse affiche les cinq noms d’autorisation. Tu as terminé.
   • Si la requête échoue avec une erreur d’autorisations (probablement DelegatedPermissionGrant.ReadWrite.All), sélectionnez l’onglet Modifier les permissions , consentez à DelegatedPermissionGrant.ReadWrite.All, puis sélectionnez Exécuter la requête à nouveau.
   • Si vous recevez une erreur Request_MultipleObjectsWithSameKeyValue: une subvention existe déjà. Peut-être que quelqu’un a ajouté des permissions plus tôt. Consultez la section Mise à jour des autorisations déléguées.

Mettre à jour les autorisations déléguées

Lorsque vous recevez une Request_MultipleObjectsWithSameKeyValue erreur en utilisant les étapes pour créer des permissions déléguées, utilisez ces étapes pour mettre à jour les permissions déléguées.

1. Réglez la méthode Graph Explorer sur GET et utilisez cette URL :

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'
   

2. Sélectionnez Exécuter la requête. Copiez la id valeur de la réponse. Cette valeur est YOUR_GRANT_ID.

3. Réglez la méthode Graph Explorer sur PATCH et utilisez cette URL avec YOUR_GRANT_ID.

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<YOUR_GRANT_ID>
   

   Corps de la demande :

   {
      "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

4. Sélectionnez Exécuter la requête. Vous devriez recevoir une 200 OK réponse avec les cinq autorisations dans le scope champ.

Bonnes pratiques de sécurité

Consultez ces directives pour garantir la sécurité et la conformité à votre inscription à votre application.

À faire :

• Utilisez l’inscription à locataire unique.
• N’accordez que les autorisations déléguées requises.
• Auditez régulièrement les autorisations.
• Supprimez l’application quand ce n’est plus nécessaire.

À ne pas faire :

• Accordez des autorisations d’application. N’utilisez que le délégué.
• Partagez publiquement l’identifiant client.
• Accordez d’autres autorisations inutiles.
• Utilisez l’application pour d’autres usages.

Étapes suivantes

Après avoir enregistré votre application client personnalisée, utilisez-la avec la CLI Agent 365 dans le cycle de développement Agent 365 :

Résolution des problèmes

Cette section explique comment dépanner les erreurs lors de l’enregistrement personnalisé d’une application client.

Échec de validation de la CLI lors de la configuration

Symptôme: Exécution de la commande ou a365 config init échoue avec des erreurs de validation concernant votre application cliente personnalisée.

Solution : Utilisez cette liste de contrôle pour vérifier que votre inscription à l’application est correcte :

# Run configuration to see validation messages
a365 config init

Résultat attendu : La CLI affiche Custom client app validation successful.

Si vous n’obtenez pas le résultat attendu, vérifiez chacune des vérifications suivantes :

Autorisations déléguées requises :

• Application.ReadWrite.All
• AgentIdentityBlueprint.ReadWrite.All [Bêta]
• AgentIdentityBlueprint.UpdateAuthProperties.All [Bêta]
• Directory.Read.All
• DelegatedPermissionGrant.ReadWrite.All

Consentement administrateur accordé incorrectement

Symptôme: La validation échoue même si des permissions sont ajoutées.

Cause profonde : Le consentement administrateur n’est pas accordé, ou est accordé incorrectement.

Solution : La bonne solution dépend de la méthode que vous avez utilisée :

Si vous utilisez accidentellement Microsoft Entra centre d’administration après l’option B : Vous supprimez vos autorisations bêta. Suivez, mettez à jour les autorisations déléguées pour les restaurer.

Mauvais type de permission

Symptôme : Échec de la ligne de commande (LI) avec des erreurs d’authentification ou des erreurs de refus d’autorisation.

Cause profonde : Vous avez ajouté des permissions Application au lieu des permissions déléguées.

Ce tableau décrit les différents types d’autorisations.

Pourquoi délégué ?

• Vous vous connectez de manière interactive (authentification du navigateur)
• CLI exécute des actions en votre nom (les pistes d'audit montrent votre identité)
• Plus sécurisé - limité par vos autorisations réelles
• Assure la responsabilité et la conformité

Solution:

1. Accédez au centre d’administration Microsoft Entra>Inscriptions d'application> Votre application >autorisations API
2. Supprimez toutes les permissions d’application. Ces permissions apparaissent sous la rubrique Application dans la colonne Type .
3. Ajoutez les mêmes permissions que les autorisations déléguées .
4. Accordez à nouveau le consentement administratif.

Les autorisations bêta disparaissent après le consentement de l'administrateur dans le centre d'administration Microsoft Entra.

Symptom : Vous avez utilisé Option B : Microsoft Graph API (Pour les autorisations bêta) pour ajouter des autorisations bêta, mais elles disparaissent après avoir sélectionné Agrégation du consentement administrateur dans Microsoft Entra centre d’administration.

Root cause : Microsoft Entra centre d'administration n'affiche pas les autorisations bêta dans l'interface utilisateur. Lorsque vous sélectionnez Accorder le consentement de l’administrateur, le portail accorde le consentement uniquement pour les autorisations visibles et écrase le consentement accordé par l’API.

Pourquoi cela se produit :

1. Vous utilisez le Graph API (Option B) pour ajouter les cinq autorisations, y compris les autorisations bêta.
2. L'appel API consentType: "AllPrincipals"accorde déjà le consentement administrateur à l'échelle du locataire.
3. Vous accédez à Microsoft Entra Centre d’administration et ne voyez que trois autorisations, car les autorisations bêta sont invisibles.
4. Vous sélectionnez Accorder le consentement administrateur en pensant que vous en avez besoin.
5. Microsoft Entra centre d'administration écrase votre consentement accordé via l'API avec seulement les trois autorisations visibles.
6. Vos deux autorisations bêta sont maintenant supprimées.

Solution:

• Ne pas utiliser le consentement administrateur du centre d'administration Microsoft Entra après la méthode API : la méthode API accorde déjà le consentement administrateur.
• Si vous supprimez accidentellement des autorisations bêta, réexécutez Option B Étape 3 (accordez le consentement administrateur à l’aide de Graph API) pour les restaurer. Si vous recevez une Request_MultipleObjectsWithSameKeyValue erreur, suivez les étapes pour mettre à jour les permissions déléguées.
• Pour vérifier que les cinq autorisations sont listées, vérifiez le champ scope dans la réponse POST ou PATCH.

Application non trouvée lors de la validation

Symptôme: Rapports Application not found ou Invalid client ID erreurs de CLI.

Solution:

1. Vérifiez que vous avez copié l’ID Application (client) au format GUID, et non l’ID de l’objet :

   • Accédez au centre d’administration Microsoft Entra>App registrations> Votre application >Overview
   • Copiez la valeur sous l’ID Application (client)
   • Le format doit être : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. Vérifiez que l’application existe dans votre locataire :

   # Sign in to the correct tenant
   az login
   
   # List your app registrations
   az ad app list --display-name "<The display name of your app>"
   

Learn comment inscrire une application dans Microsoft Entra ID.