Configuration guidée par l’IA pour Identifiant d’assistant Microsoft Entra

L’intégration Identifiant d’assistant Microsoft Entra implique plusieurs étapes : création d’un blueprint d’identité d’agent, configuration des identifiants, configuration des URI et des portées d’identifiants, création de principes de blueprints et provisionnement des identités d’agent. Chaque étape a ses propres prérequis, vérifications de validation et points de décision.

Cette configuration guidée par l’IA automatise tout ce flux de travail à l’aide d’un agent de codage IA (tel que GitHub Copilot dans VS Code) pour exécuter les étapes en votre nom. Au lieu de naviguer entre plusieurs pages de documentation et d’exécuter manuellement des commandes, vous fournissez à l’agent IA un seul fichier d’instructions qui vous guide de manière interactive à travers le processus.

Avantages

La configuration guidée par IA offre plusieurs avantages par rapport au flux de travail manuel :

• Point d’entrée unique : un fichier d’instructions remplace la nécessité de naviguer entre plusieurs pages de documentation. L’agent IA suit les étapes dans l’ordre et gère automatiquement les transitions.
• Validation automatisée des prérequis : l’agent IA vérifie que vous disposez des rôles Microsoft Entra appropriés, que le module Microsoft Graph en version bêta est installé et que les autorisations nécessaires sont configurées avec le consentement de l’administrateur avant d’effectuer des appels d’API.
• Valeurs par défaut intelligentes et détection automatique : l’agent IA interroge votre locataire pour obtenir des informations utilisateur et des informations sur les ressources existantes, puis utilise ces valeurs comme suggestions lors de la collecte d’entrées de configuration.
• Conventions de nommage dérivées : vous fournissez un nom d'affichage unique pour votre agent, et l'agent IA dérive tous les noms de ressources associés (blueprint, principal de blueprint, identités d'agent, URIs d'identification) en utilisant des modèles cohérents.
• Gestion des erreurs inline : en cas d’échec d’une commande, l’agent IA analyse l’erreur, suggère un correctif et retente plutôt que de vous obliger à effectuer une recherche dans la documentation de dépannage. Cette gestion des erreurs est particulièrement utile pour les pièges spécifiques à l’ID de l’agent, tels que les retards de propagation des autorisations et les exigences d’en-tête OData.
• Opérations idempotentes : l’agent IA vérifie si des ressources existent déjà avant de les créer, ce qui permet de réexécuter l’installation si une tentative précédente a été interrompue.

Prerequisites

Avant de commencer, vérifiez que vous disposez des conditions préalables suivantes.

Outils requis

• Visual Studio Code avec les extensions GitHub Copilot et GitHub Copilot Chat installées. La configuration guidée par IA nécessite un agent de codage IA avec accès au terminal.
• PowerShell 7 ou version ultérieure est nécessaire pour le module PowerShell Microsoft Graph.
• Microsoft Graph - SDK PowerShell (bêta) installé à l’aide de Install-Module Microsoft.Graph.Beta.Applications -Scope CurrentUser -Force.

Comptes et autorisations requis

• Accès à un client Microsoft Entra avec l’un des rôles suivants :
  • Développeur d’ID d’agent pour créer des plans d’identité d’agent et des identités d’agents. Tout propriétaire d’un blueprint d’identité d’agent peut créer une identité d’agent pour ce blueprint sans rôle d’ID d’agent.
  • Administrateur d’ID d’agent pour un accès administratif complet aux ressources d’ID d’agent.

• Rôles supplémentaires pour les octrois d’autorisations :
  • Administrateur de rôle privilégié pour accorder des autorisations d’application Microsoft Graph.
  • Cloud Application Administrator ou Application Administrator pour accorder des autorisations déléguées Microsoft Graph.

Autorisations de Microsoft Graph requises

Le client que vous utilisez (PowerShell ou une inscription d’application personnalisée) doit être autorisé avec les autorisations déléguées suivantes :

Code d’agent requis (facultatif)

Si vous avez déjà un projet d’agent opérationnel (Python, Node.jsou .NET) qui a besoin d’une identité d’ID d’agent, disposez du répertoire du projet disponible. Si vous n’en avez pas encore, vous pouvez toujours effectuer la configuration du blueprint indépendamment.

Obtenez le fichier d’instructions de configuration

L’installation guidée par l’IA utilise les instructions figurant dans le référentiel Microsoft Skills GitHub.

Exécutez la configuration guidée par l’IA

Suivez ces étapes pour démarrer la configuration guidée par l’IA.

Étape 1 : Ouvrir votre projet dans VS Code

Ouvrez le répertoire de votre projet d’agent (ou tout répertoire de travail) dans Visual Studio Code.

Étape 2 : Ouvrir gitHub Copilot Chat en mode agent

Ouvrez le panneau Copilot Chat GitHub et basculez vers le mode Agent. Le mode Agent offre GitHub Copilot la possibilité d’exécuter des commandes de terminal, de lire des fichiers et d’interagir avec votre environnement, dont la configuration guidée par l’IA nécessite.

Étape 3 : Attachez le fichier d’instructions et commencez

Dans l’entrée Copilot Chat, joignez le fichier agent-id-setup-instructions.md et envoyez-le avec une courte instruction. Par exemple:

Follow the steps in #file:agent-id-setup-instructions.md

L’agent IA lit le fichier d’instructions et commence la mise en place guidée. Il crée une liste de tâches et effectue les étapes de manière séquentielle :

1. Valider les prérequis : Vérifie les rôles Microsoft Entra, valide que PowerShell 7+ et le module bêta Microsoft Graph sont installés.
2. Autoriser et se connecter : Se connecte à Microsoft Graph avec les périmètres requis et met le profil en bêta.
3. Créez le plan d’identité de l’agent: Collecte un nom d’affichage, identifie le sponsor (vous), crée le plan avec les en-têtes @odata.type et OData-Version requis, et enregistre le appId.
4. Configurez les informations d’identification : ajoute une identité managée (pour la production) ou un certificat ou une clé secrète client (pour le développement/test local) au blueprint.
5. Configurez l’identifiant URI et la portée : Définit identifierUris à api://{appId}, crée une access_agent portée d’autorisation OAuth2 pour la communication agent-à-agent et utilisateur-à-agent.
6. Créer le principe du blueprint : Crée le principal de service pour le blueprint (le principal n’est pas créé automatiquement et doit être fait explicitement).
7. Créer des identités d’agent : Crée un ou plusieurs principaux responsables de service d’identité d’agent sous le blueprint.

Étape 4 : Répondre aux consignes

L’agent IA fait une pause à des moments précis pour recueillir vos commentaires :

• Nom d’affichage : Le nom d'affichage de votre modèle d'identité d'agent (par exemple, « Agent budgétaire Contoso »).
• Sponsor : utilisateur ou groupe responsable de l’agent. La valeur par défaut est l’utilisateur actuellement connecté.
• Propriétaire : l’utilisateur ou le principal du service qui peut apporter des modifications techniques au blueprint. Facultatif mais recommandé.
• Type d’informations d’identification : indique s’il faut utiliser une identité managée (recommandée pour la production) ou un certificat ou une clé secrète client (pour le développement local).
• Nombre d’identités de l’agent : nombre d’identités d’agent à créer sous ce blueprint.
• Confirmation de la valeur dérivée : passez en revue les noms et URI générés automatiquement avant la création des ressources.

Étape 5 : Vérifier dans le centre d’administration Microsoft Entra

Une fois l’installation terminée, l’agent IA fournit des instructions sur la façon de vérifier les ressources :

1. Connectez-vous au centre d’administration Microsoft Entra comme au moins un développeur Agent ID.
2. Accédez à Entra ID>Agents> IdentitésAgent pour voir votre nouveau blueprint d’identité d’agent et toutes les identités d’agent créées sous celui-ci.
3. Vérifiez que le blueprint a les bons identifiants, l’URI d’identifiant et le périmètre de portée configurés.

Ce que couvre la configuration guidée par IA

La configuration guidée par l’IA automatise les étapes suivantes de l’intégration de l’ID d’agent :

Les pièges courants gérés par la configuration guidée par l'IA

Les API d’ID d’agent ont plusieurs exigences que la configuration guidée par l’IA détecte et résout automatiquement, mais elles ne sont pas des exigences évidentes. La compréhension de ces pièges peut être utile si vous avez besoin de déboguer des problèmes ou d’étendre l’installation.

L'en-tête OData-Version est requis

Tous les appels d’API d’ID d’agent qui utilisent @odata.type nécessitent l’en-tête OData-Version: 4.0 . Si vous omettez cet en-tête, le @odata.type champ est ignoré en mode silencieux, ce qui entraîne la création d’une application standard au lieu d’un blueprint d’identité d’agent. La configuration guidée par l’IA inclut toujours cet en-tête.

Le principal élément du blueprint n'est pas créé automatiquement

La création d’un blueprint d’identité d’agent (POST /applications) ne crée pas automatiquement son principal de blueprint (principal de service). Sans le principe de blueprint, toute création d’identité d’agent ultérieure échoue avec :

400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

La configuration assistée par l’IA crée toujours le plan principal immédiatement après le plan. Il traite également le cas des idempotents. Si une exécution précédente a créé le blueprint mais s’est bloquée avant de créer le principal, le programme d’installation détecte cet événement et crée le principal manquant.

Les commanditaires sont requis

Les sponsors sont requis et peuvent être des utilisateurs, des groupes avec appartenance dynamique ou des groupes unifiés. La création de blueprint et d’identité d’agent nécessitent tous deux un sponsors@odata.bind champ. Sans cela, vous recevez :

400: No sponsor specified. Please provide at least one sponsor.

La configuration guidée par l’IA accepte uniquement les objets utilisateur pour l’attribution de sponsor et utilise le /users/{objectId} format d’URL (non /directoryObjects/ ou /servicePrincipals/). Le programme d’installation résout l’ID d’objet de l’utilisateur actuel et l’utilise comme sponsor par défaut. Pour affecter un groupe supporté en tant que sponsor pour un blueprint, utilisez directement microsoft API Graph.

La propagation des autorisations prend 30 à 120 secondes ou plus.

Après avoir accordé le consentement de l’administrateur pour les autorisations d’ID d’agent, les autorisations nouvellement accordées n’apparaissent pas immédiatement dans les jetons. Le point de terminaison du jeton sert les revendications mises en cache, et la propagation peut prendre 30 à 120 secondes ou plus.

La configuration guidée par l’IA gère les changements récents de permissions en réessayant les opérations avec un retour exponentiel lorsqu’un 403 est reçu. Si vous écrivez un script manuellement, implémentez la logique de nouvelle tentative :

# Example: Retry with backoff after admin consent
$maxRetries = 5
for ($i = 0; $i -lt $maxRetries; $i++) {
    try {
        # Attempt the operation
        $result = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body
        break
    } catch {
        if ($_.Exception.Response.StatusCode -eq 403 -and $i -lt $maxRetries - 1) {
            $wait = 20 * ($i + 1)
            Write-Host "Permission not yet propagated. Retrying in $wait seconds..."
            Start-Sleep -Seconds $wait
            # Disconnect and reconnect to force a fresh token
            Disconnect-MgGraph
            Connect-MgGraph -Scopes $scopes
        } else {
            throw
        }
    }
}

Les identités d’agent ne peuvent pas avoir d’identifiants de mot de passe

Les identités des agents sont des principaux de service sans objet d’application de soutien. Si vous tentez d’ajouter un passwordCredential directement à une identité d’agent, cela entraîne :

PropertyNotCompatibleWithAgentIdentity

Les informations d’identification doivent être configurées sur le blueprint, et non sur les identités d’agent individuelles. Utilisez la fédération d’identité gérée (recommandée) ou ajoutez des secrets/certificats au blueprint, et les identités des agents héritent de la certification par usurpation d’identité.

L’URI d’identificateur doit être défini explicitement

Le champ du identifierUris blueprint n’est pas défini par défaut. Sans cela, le scope api://{appId}/.default OAuth2 ne se résoudra pas, et l'acquisition de jetons pour l'agent échouera. La configuration guidée par l’IA configure toujours cette valeur dans le cadre de l’étape de configuration de l’étendue.

Chemin fédéré d’identification pour les plans

Lors de l’ajout de crédents d’identité fédérés (FIC) pour la fédération d’identité gérée, vous devez utiliser le chemin API spécifique à l’agent :

POST /applications/{blueprint-obj-id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials

Utiliser le /applications/{id}/federatedIdentityCredentials chemin peut fonctionner pour les blueprints d'identité d'agent, mais ce n'est pas pris en charge et n'est pas recommandé.

L’émetteur de jeton varie selon la version du point de terminaison

Lors de la validation des jetons dans le serveur de votre agent, tenez compte des variantes suivantes :

• Les jetons v1.0 utilisent l’émetteur https://sts.windows.net/{tenant-id}/
• Les jetons v2.0 utilisent l’émetteur https://login.microsoftonline.com/{tenant-id}/v2.0

Acceptez les deux formats dans votre logique de validation de jeton.

Résolution des problèmes

L’agent IA n’exécute pas les commandes terminales

Si l'agent IA décrit les commandes mais ne les exécute pas, vérifiez que vous utilisez ModeAgent dans GitHub Copilot Chat. Les modes Demande et Édition n’ont pas accès au terminal.

L’agent IA saute les étapes de validation

Le fichier d’instructions impose un ordre strict des pas. Si l’agent IA semble sauter une étape, rappelez-lui de suivre les instructions dès le début. Par exemple:

Please start from Step 1 in the setup instructions and work through each step in order.

Échec des commandes Graph avec 403-Interdit

Les causes les plus courantes des erreurs 403 :

• Délai de propagation des autorisations : attendez 1 à 2 minutes après le consentement de l’administrateur et réessayez.
• Consentement administrateur manquant : vérifiez que les autorisations requises disposent du consentement administrateur accordé dans le centre d'administration Microsoft Entra sous enregistrements d'applications> votre application cliente >autorisations d'API.

La création de Blueprint réussit, mais renvoie une application standard

Ce résultat se produit lorsque l’en-tête OData-Version: 4.0 est manquant ou que la @odata.type propriété est omise. Vérifiez que les deux sont présents dans la requête. Si vous utilisez des cmdlets PowerShell, assurez-vous d'utiliser le module bêta et de respecter la bonne structure corporelle.

La création de l'identité de l'agent échoue avec « Le principal de Blueprint n'existe pas »

Le principe du blueprint doit être créé comme une étape séparée après le blueprint. Exécutez :

POST https://graph.microsoft.com/beta/serviceprincipals/microsoft.graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json

{
  "appId": "<your-blueprint-app-id>"
}

Erreurs de politique de durée de vie des informations d’identification

Votre instance de cloud peut avoir des stratégies de cycle de vie des informations d’identification qui limitent la durée de vie maximale des secrets client. Si vous recevez une erreur concernant la durée de vie des informations d’identification lors de l’ajout d’un mot de passe, réduisez la valeur de endDateTime pour qu'elle soit alignée sur la stratégie de votre organisation.

Les valeurs de configuration doivent être modifiées

Si vous devez modifier les valeurs de configuration après l’installation, vous pouvez :

• Réexécutez la configuration guidée par l’IA avec des valeurs mises à jour. Les tests d’idempotents sautent correctement des ressources qui existent déjà.
• Utilisez Microsoft Graph PowerShell pour mettre à jour des propriétés spécifiques avec des requêtes PATCH.

Étapes suivantes

• Créer et supprimer des identités d’agent
• Relations administratives dans l’identifiant de l’agent (propriétaires, commanditaires et gestionnaires)
• Identités d’agent, principaux de service et applications
• Concepts du blueprint d’identité de l’agent