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

La CLI Agent 365 nécessite une inscription personnalisée à l’application client dans votre locataire Microsoft Entra ID pour authentifier et gérer les Blueprints d’identité d’agent.

Prerequisites

Pour enregistrer l’application (Étapes 1 et 2) :

• 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é.

Pour ajouter des autorisations et accorder le consentement (Étape 3) :

• L’un de ces rôles administratifs est requis :
  • Administrateur de la candidature : recommandé - peut gérer les inscriptions aux 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

Étape 1 : Enregistrer la demande

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

1. Rendez-vous au centre d’administration Microsoft Entra
2. Sélectionnez les inscriptions à l’application
3. Sélectionnez Nouvelle inscription
4. Entrée:
   • Nom : Agent365 CLI (ou votre prénom préféré)
   • Types de comptes pris en charge : comptes dans ce répertoire organisationnel uniquement (locataire unique)
   • Redirection URI : Sélectionnez Client/natif public (mobile et bureau) → Entrer http://localhost:8400/
5. Sélectionnez Inscrire.

Étape 2 : Copier l’ID de l’application (client)

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

Étape 3 : Configurer les permissions de l’API

Choisissez la méthode appropriée :

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

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

Utilisez cette méthode si les autorisations bêta sont visibles dans votre locataire.

1. Dans votre inscription à l’application, allez dans les permissions API

2. Sélectionnez Ajouter une permission → 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 plans 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 la permission
   • Sélectionner Ajouter des autorisations
   • Répétez pour les cinq permissions

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 permissions affichent des coches vertes sous Statut

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

Option B : API Microsoft Graph (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. Open Graph Explorer

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

3. Accordez le consentement administrateur via Graph API. Pour compléter cela, vous devez :

   • ID de principal du service. Il te faudra une SP_OBJECT_ID valeur variable.
   • ID de ressource du graphe. Il te faudra 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 SP_OBJECT_ID valeurs des variables et GRAPH_RESOURCE_ID .

Utilisez les informations des sections suivantes pour compléter cela.

Obtenez votre ID de principal de service

Un principal de service est l’identité de votre application dans votre locataire, requise avant d’accorder les autorisations via l’API.

1. Réglez la méthode Graph Explorer sur GET et utilisez cette URL (remplacez-la <YOUR_CLIENT_APP_ID> par votre ID client d’application réel à l’étape 2 : Copier l’ID de l’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 à cause d’une erreur d’autorisation, 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. Voici votre GRAPH_RESOURCE_ID.
   • Si la requête échoue à cause d’une erreur d’autorisation, 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. Voici votre GRAPH_RESOURCE_ID.

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

Cet appel API accorde le consentement administrateur à l’échelle du locataire pour les cinq permissions, 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 de permissions (probablement DelegatedPermissionGrant.ReadWrite.All), sélectionnez l’onglet Modifier les permissions , consentir à DelegatedPermissionGrant.ReadWrite.All, puis sélectionnez à nouveau Exécuter la requête .
   • Si vous recevez une erreur Request_MultipleObjectsWithSameKeyValue: une subvention existe déjà. Peut-être que quelqu’un a ajouté des permissions plus tôt. Voir la mise à jour suivante 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 valeur id de la réponse. Voici YOUR_GRANT_ID.

3. Réglez la méthode Graph Explorer sur PATCH et utilisez cette URL en utilisant 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 sur le scope terrain.

Résolution des problèmes

Cette section contient des informations sur la manière de dépanner les erreurs lors de l’enregistrement personnalisé d’une application client.

Mauvais type d’autorisation (Délégué vs Application)

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.

Pourquoi délégué ?

• Vous vous connectez de manière interactive (authentification du navigateur)
• CLI effectue des actions comme vous (les audittrails montrent votre identité)
• Plus sécurisé - limité par vos autorisations réelles
• Assure la responsabilité et la conformité

Solution:

1. Rendez-vous sur le centre >d’administration Microsoft EntraEnregistrements> d’applications Vos autorisations API d’application >
2. Supprimez toutes les permissions d’application (celles-ci apparaissent comme « Application » dans la colonne Type )
3. Ajouter les mêmes permissions que les permissions déléguées
4. Accordez à nouveau le consentement administrateur

Les permissions bêta disparaissent après le consentement de l’administrateur du centre d’administration Microsoft Entra

Symptôme : Vous avez utilisé l’option B : l’API Microsoft Graph (pour les autorisations bêta) pour ajouter des autorisations bêta, mais elles ont disparu après avoir sélectionné Accorder le consentement administrateur dans le centre d’administration Microsoft Entra.

Cause principale : le centre d’administration Microsoft Entra n’affiche pas les permissions bêta dans l’interface, donc lorsque vous sélectionnez Accorder le consentement d’admin, il n’accorde que les autorisations visibles et écrase le consentement accordé par l’API.

Pourquoi cela se produit :

1. Vous utilisez l’API Graph (option B) pour ajouter les cinq permissions, y compris les permissions bêta
2. L’appel API accorde déjà le consentement administrateur à l’échelle du locataireconsentType: "AllPrincipals"
3. Vous allez dans le centre d’administration Microsoft Entra et ne voyez que trois permissions car les permissions bêta sont invisibles
4. Vous sélectionnez Accorder le consentement administrateur en pensant que c’est nécessaire
5. Le centre d’administration Microsoft Entra écrase votre consentement accordé par l’API avec seulement les trois autorisations visibles
6. Vos deux autorisations bêta sont désormais supprimées

Solution:

• Ne jamais 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 avez accidentellement supprimé les permissions bêta, relancez l’option B Étape 3 (accorder le consentement administrateur via l’API Graph) pour les restaurer. Vous obtenez une Request_MultipleObjectsWithSameKeyValue erreur - suivez les étapes pour mettre à jour les permissions déléguées.
• Vérifiez le scope champ dans la POST réponse ou PATCH pour vérifier que les cinq autorisations sont listées

Erreurs de validation

La CLI valide automatiquement votre application cliente lors de l’exécution a365 setup ou a365 config init.

Problèmes courants :

• Application non trouvée : Vérifiez que vous avez copié l’ID Application (client) (et non l’ID de l’objet)
• Permissions manquantes : Ajoutez les cinq permissions requises
• Consentement administrateur non accordé :
  • Si vous avez utilisé l’option A (uniquement le centre d’administration Microsoft Entra) : Sélectionnez Accorder le consentement administrateur dans le centre d’administration Microsoft Entra
  • Si vous avez utilisé l’option B (API Graph) : Relancer la POST requête ou.PATCH NE PAS utiliser le bouton de consentement du centre d’administration Microsoft Entra
• Mauvais type d’autorisation : Utilisez les autorisations déléguées, pas les autorisations d’application

Pour un dépannage détaillé, voir Enregistrer une application dans Microsoft Entra ID.

Bonnes pratiques de sécurité

À faire :

• Utilisez l’enregistrement en locataire unique
• N’accordez que les cinq 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 :

• Autorisations d’attribution de demande (Utilisation déléguée uniquement)
• Partagez publiquement l’identifiant client
• Accordez d’autres autorisations inutiles
• Utilisez l’application à d’autres fins

Étapes suivantes

Maintenant que vous avez enregistré votre application client personnalisée, vous pouvez l’utiliser avec la CLI Agent 365 :

• Commencez avec l’interface de l’Agent 365 - Installez et configurez la ligne de commande avec votre application client
• Configurez le blueprint et l’instance de l’agent - Créez et configurez l’identité de votre agent
• Déploie et publie des agents - Déploie ton agent sur Azure et publie sur Microsoft 365