Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Enregistrez votre agent afin qu’il puisse s’authentifier avec Microsoft Entra ID et demander l’accès aux API. Cette configuration crée une seule identité pour votre agent, partagée par ses installations ou ses réplicas.
Cette procédure utilise Microsoft Graph bêta. Pour un agent cloud, configurez des informations d’identification pour son runtime. Pour un agent installé sur un appareil utilisateur final, utilisez la configuration de redirection du client public sans informations d’authentification. Votre tutoriel sur les appels identifie les sections dont vous avez besoin.
Important
Les identités d’agent à instance unique sont en préversion. Cette version préliminaire est fournie sans contrat de niveau de service et n’est pas recommandée pour les environnements de production. Certaines fonctionnalités peuvent ne pas être prises en charge ou avoir des fonctionnalités limitées. Pour plus d’informations, consultez Conditions du contrat de licence universel pour les services en ligne.
Prerequisites
- Un tenant Microsoft Entra activé pour l’approvisionnement à instance unique dans Microsoft Graph. Confirmez la disponibilité en préversion et l’activation du locataire avec votre représentant Microsoft avant de commencer. Pour demander des jetons après l’installation, vérifiez également que l’authentification à instance unique est activée ; le provisionnement et l’authentification sont activés séparément.
- Un compte autorisé à créer et mettre à jour des plans d’identité d’agent et des identités d’agent, tels qu’un administrateur d’ID d’agent.
- Une application de gestion publique à locataire unique distincte avec le consentement de l’administrateur pour les autorisations
AgentIdentityBlueprint.ReadWrite.Allde Microsoft Graph déléguées etAgentIdentity.ReadWrite.All, ou l’autorisation de configurer le client de gestion. - Administrateur qui peut accorder le consentement aux autorisations Graph de l’application de gestion.
- ID d’objet d’un utilisateur pouvant être affecté en tant que sponsor du blueprint. Les exemples désignent également cet utilisateur comme propriétaire.
- Pour la connexion interactive, une URI de redirection appropriée pour le type de client. Pour le consentement de l’administrateur basé sur un navigateur, utilisez un URI de redirection
web, même si l’agent utilise uniquement les informations d’identification du client au moment de l’exécution. - Pour les tests de client confidentiel local, un certificat X.509 et un stockage sécurisé pour sa clé privée. Un agent hébergé par Azure peut utiliser un justificatif d’identité fédérée pour identité managée à la place. Un client de type public uniquement n’a pas besoin d’informations d’identification.
- Pour l’accès à l’API, l’ID client de l’application de ressource et les ID des autorisations déléguées ou des rôles d’application dont l’agent a besoin.
Exécutez les exemples HTTP via Microsoft Graph PowerShell, comme décrit ci-dessous, ou utilisez un client REST capable d’envoyer des corps et des en-têtes de requête JSON. Dans un client REST, envoyez le jeton de gestion en tant que jeton de porteur dans l’en-tête Authorization de chaque requête Graph. N’utilisez jamais le jeton d’accès d’exécution de l’agent pour les demandes de gestion.
Confirmer la passation de l’administrateur
Avant de créer des objets, convenez de la procédure de passation suivante. Le consentement de gestion et le consentement de l’API d’exécution de l’agent sont des approbations distinctes.
| Qui | Action | Prêt quand |
|---|---|---|
| Administrateur de locataire et représentant Microsoft. | Vérifiez que l’approvisionnement en préversion et l’authentification en préversion sont activés. | Le locataire prend en charge les demandes d’inscription et de jeton pour cette configuration. |
| Administrateur autorisé. | Approuvez les deux autorisations Graph du client de gestion répertoriées ci-dessus. | L’opérateur peut se connecter à ce client avec les deux portées consenties. |
| Développeur ou opérateur autorisé. | Effectuez les étapes d’inscription ci-dessous. | L’ID d’objet blueprint, l’ID d’objet d’identité de l’agent et l’ID client partagé sont enregistrés. |
| Propriétaire de l’API et administrateur de consentement. | Fournissez les identificateurs d’API et approuvez les autorisations requises par le didacticiel appelant. | Les autorisations d’exécution requises sont vérifiées avant le premier appel d’API. |
Envoyez à l’administrateur votre ID de locataire, l’ID client de gestion et les autorisations d’API demandées. Conservez la feuille de calcul d’identificateur en même temps que les étapes de configuration.
Si vous suivez un didacticiel HTTPS local, vérifiez également que le certificat HTTPS de développement est approuvé sur votre ordinateur avant la connexion du navigateur. Suivez le processus de confiance de votre organisation plutôt que de désactiver la validation TLS.
Configurer le client de gestion
Le client de gestion connecte un administrateur ou un opérateur autorisé pour créer l’inscription de l’agent. Elle est distincte de l’identité d’exécution de l’agent. Une connexion Azure CLI existante n'établit pas ce contexte de gestion.
Enregistrez une application dans le même tenant. Sélectionnez Comptes dans ce répertoire organisationnel uniquement. Sous Authentification, ajoutez la plateforme d’applications mobiles et de bureau avec l’URI
http://localhostde redirection.Sous Autorisations de l’API, ajoutez ces autorisations déléguées Microsoft Graph > :
-
AgentIdentityBlueprint.ReadWrite.All. -
AgentIdentity.ReadWrite.All.
-
Demandez à un administrateur autorisé d’accorder son consentement à ces autorisations. Pour plus d’informations sur le consentement de l’administrateur, consultez Autorisations et consentement dans le Plateforme d'identités Microsoft.
Installez le module d’authentification PowerShell Microsoft Graph et connectez-vous avec l’application de gestion.
Connect-MgGraphouvre un navigateur pour l’utilisateur connecté :Install-Module Microsoft.Graph.Authentication -Scope CurrentUser Connect-MgGraph ` -ClientId "<management-app-client-id>" ` -TenantId "<tenant-id>" ` -Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All" ` -ContextScope Process $context = Get-MgContext if (-not $context -or -not $context.Account) { throw "Microsoft Graph sign-in didn't establish a delegated management context. Stop before creating objects." } $context | Select-Object Account, TenantId, ClientId, ScopesVérifiez que
Account,TenantIdetClientIdidentifient l’opérateur, le locataire et l’application de gestion prévus, et queScopesinclut les deux autorisations. Si une étendue est manquante ou si le consentement est demandé à nouveau, arrêtez et demandez à un administrateur autorisé de vérifier l’inscription et le consentement de l’application avant de continuer.
Sur Windows, si Connect-MgGraph échoue avant la connexion avec Un handle de fenêtre doit être configuré, utilisez l’option de connexion de navigateur documentée pour votre client de gestion personnalisée :
Set-MgGraphOption -DisableLoginByWAM $true
Réexécutez la même Connect-MgGraph commande. Cela modifie l’interface utilisateur d’authentification, et non les exigences d’accès du locataire ; terminez la connexion en tant qu’opérateur autorisé et ne contournez pas un déni de conformité. Le paramètre persiste dans les sessions PowerShell. Si WAM a été activé avant cette modification, restaurez-le avec Set-MgGraphOption -DisableLoginByWAM $false lorsque vous avez terminé.
Utilisez Invoke-MgGraphRequest pour exécuter les exemples HTTP sans copier ou afficher un jeton d’accès. Par exemple, copiez le corps JSON de Créer le blueprint dans $body, en remplaçant l’espace réservé du sponsor :
$body = @'
<JSON-request-body>
'@
$blueprint = Invoke-MgGraphRequest -Method POST `
-Uri "https://graph.microsoft.com/beta/applications" `
-Headers @{ "OData-Version" = "4.0" } `
-ContentType "application/json" -Body $body
$blueprintObjectId = $blueprint.id
$agentClientId = $blueprint.appId
Pour les requêtes ultérieures, utilisez la méthode, l’URI complet, les en-têtes et le corps JSON affichés dans chaque exemple HTTP. Omettez -Body pour une requête GET. Le module fournit l’en-tête d’autorisation. Pour obtenir la syntaxe de commande, consultez Invoke-MgGraphRequest.
Si l’inscription ou le consentement est refusé, demandez à votre administrateur du locataire de terminer cette configuration. N’accordez pas ces autorisations de gestion à l’agent pour contourner une erreur d’autorisation.
Créer le blueprint
Le blueprint est l’enregistrement qui contient les paramètres d’authentification et les informations d’identification de votre agent.
Créez le blueprint avec
isSingleInstancedéfini surtrue. Remplacez<sponsor-user-object-id>par l’ID d’objet du sponsor. Un sponsor est requis ; l’affectation du propriétaire est facultative.Conservez
isSingleInstance: truepour ce didacticiel : il crée une identité pour l’agent, y compris ses installations ou ses réplicas. Cette propriété ne peut pas être modifiée après la création.POST https://graph.microsoft.com/beta/applications OData-Version: 4.0 Content-Type: application/json { "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint", "displayName": "Contoso Operations Agent", "signInAudience": "AzureADMyOrg", "isSingleInstance": true, "sponsors@odata.bind": [ "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>" ], "owners@odata.bind": [ "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>" ] }À partir de la
201 Createdréponse, enregistrez les valeurs suivantes :-
id: ID d'objet du blueprint, utilisé pour l'adresser dans Microsoft Graph. -
appId: ID d’application (client), utilisé dans les requêtes OAuth.
-
L’exemple crée un blueprint monolocataire avec signInAudience défini sur AzureADMyOrg.
Provisionner l’identité de l’agent
Créez l’identité séparément de son enregistrement dans le blueprint. Suivez la demande ci-dessous directement ; cette configuration ne nécessite pas de principal de blueprint.
Créez l’ID de l’agent. Définissez
agentIdentityBlueprintIdsur l’ID d’objet du blueprint, et non sur sonappId.POST https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity OData-Version: 4.0 Content-Type: application/json { "displayName": "Contoso Operations Agent", "agentIdentityBlueprintId": "<blueprint-object-id>", "sponsors@odata.bind": [ "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>" ] }Enregistrez l’
idde l’identité à partir de la réponse201 Created. Il s’agit de l’ID d’objet de l’identité de l’agent, et non de l’ID d’objet blueprint ou de l’ID client OAuth.Lisez l’identité pour vérifier le résultat :
GET https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-object-id>?$select=id,appId,displayName,agentIdentityBlueprintId,instanceModeVérifiez les valeurs retournées :
Propriété Valeur attendue @odata.type#microsoft.graph.agentIdentity.appIdLe appIddu blueprint.agentIdentityBlueprintIdID d’objet du blueprint. instanceModesingleInstance.
Ne provisionnez pas une nouvelle identité pour chaque installation, processus ou session utilisateur. Ils utilisent le même ID client.
Configurer des URI de redirection
Pour le flux de code d’autorisation, inscrivez l’URI de redirection sous la plateforme qui correspond au client. Un client confidentiel utilise web; un client public utilise publicClient.
La procédure de consentement de l’administrateur basé sur le navigateur nécessite également un web URI de redirection, même pour un agent qui utilise uniquement les informations d’identification du client au moment de l’exécution. La redirection gère le rappel de consentement, et non la demande de jeton avec les informations d’identification du client. Ignorez cette section uniquement si aucun flux de code d’autorisation ni le consentement de l’administrateur basé sur le navigateur n’est nécessaire.
Lisez la configuration de redirection actuelle :
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClientMettez à jour la collection de redirection appropriée. L’exemple suivant montre les deux types de clients ; incluez uniquement les plateformes que votre agent utilise. Conservez toutes les URI de redirection existants qui sont toujours nécessaires.
PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id> OData-Version: 4.0 Content-Type: application/json { "@odata.type": "#microsoft.graph.agentIdentityBlueprint", "web": { "redirectUris": [ "https://agent.contoso.com/signin" ] }, "publicClient": { "redirectUris": [ "http://localhost" ] } }Une mise à jour réussie retourne
204 No Content. Les collections d’URI de redirection sont remplacées, et non ajoutées en fin de liste. Ne copiez pas cet exemple sur une configuration existante sans conserver ses URI.
Le même blueprint peut inscrire les deux plateformes. Chaque demande d’autorisation utilise l’URI de redirection pour son type de client. Un client public n’envoie pas d’informations d’identification, même si un composant confidentiel utilise un certificat sur le même blueprint. Ne changez isFallbackPublicClient pas pour basculer entre ces scénarios de code d’autorisation.
Ajouter un certificat pour les clients confidentiels
Pour les tests de client confidentiel local, inscrivez uniquement le certificat public sur le blueprint. Le runtime conserve la clé privée pour l’authentification.
Passez cette section pour un client public uniquement. Pour un agent hébergé par Azure à l’aide de la fédération d’identité managée, configurez les informations d’identification fédérées à la place, puis poursuivez avec Déclarer les autorisations d’API.
Pour une machine de développement Windows, vous pouvez créer un certificat auto-signé et exporter son certificat public et son PFX protégé par mot de passe. Conservez le PFX en dehors de votre arborescence source. Utilisez le certificat public DER codé en base64 pour key ci-dessous, et non le PFX ni l’en-tête et le pied de page d’un fichier PEM. Par exemple:
$publicCertificate = Get-PfxCertificate -FilePath "<absolute-path-to-public-cer>"
$publicCertificateBase64 = [Convert]::ToBase64String($publicCertificate.RawData)
Collez $publicCertificateBase64 dans la demande d’inscription. La valeur publique n’est pas une information d’identification ; PFX et son mot de passe sont. Pour le développement ou la production non-Windows, utilisez le processus d'émission de certificat et de stockage de clé privée de votre organisation.
Lisez la collection de certificats actuelle :
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentialsAjoutez votre certificat public tout en conservant les informations d’identification de clé existantes qui sont toujours nécessaires. La requête suivante montre une inscription initiale sans certificats existants :
PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id> OData-Version: 4.0 Content-Type: application/json { "@odata.type": "#microsoft.graph.agentIdentityBlueprint", "keyCredentials": [ { "type": "AsymmetricX509Cert", "usage": "Verify", "key": "<base64-encoded-DER-certificate>", "displayName": "Contoso Operations Agent certificate" } ] }Une mise à jour réussie retourne
204 No Content. Ne chargez jamais la clé privée et ne la distribuez pas avec un client public.
Pour obtenir des conseils sur le format de certificat et l’assertion du client, consultez Plateforme d'identités Microsoft certificats d’authentification.
Déclarer les autorisations d’API
Déclarez uniquement les autorisations dont l’agent a besoin. Utiliser Scope pour une autorisation déléguée et Role pour une autorisation d’application. Les valeurs dans resourceAccess ce sont des ID d’autorisation exposés par l’application de ressource, et non des noms d’autorisations.
Lisez les déclarations actuelles :
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccessAjoutez les entrées de ressource et d’autorisation, en conservant les déclarations existantes qui sont toujours nécessaires. L’exemple montre une autorisation déléguée et une autorisation d’application ; supprimez l’une ou l’autre entrée si votre agent n’en a pas besoin.
PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id> OData-Version: 4.0 Content-Type: application/json { "@odata.type": "#microsoft.graph.agentIdentityBlueprint", "requiredResourceAccess": [ { "resourceAppId": "<resource-app-id>", "resourceAccess": [ { "id": "<delegated-permission-id>", "type": "Scope" }, { "id": "<app-role-id>", "type": "Role" } ] } ] }Une mise à jour réussie retourne
204 No Content.
Ces déclarations n’accordent pas l’accès. Le consentement de l’utilisateur ou de l’administrateur accorde des autorisations déléguées et un administrateur accorde des autorisations d’application. Les autorisations sont directement associées à l’ID de l’agent.
Si l’agent reçoit également des appels d’une application front-end, exposez un URI d’identificateur et une portée déléguée sur le blueprint. Conservez les étendues d’API existantes et définissez requestedAccessTokenVersion sur 2. Le front-end demande ce scope pour obtenir un jeton dont l’audience est l’ID client partagé.
Résoudre les problèmes liés aux demandes Graph
En cas d’échec d’une requête, inspectez l’état HTTP et la réponse d’erreur Graph avant de modifier les autorisations ou de réessayer l’opération.
| Response | Cocher |
|---|---|
400 Bad Request |
Lire error.code et error.message. Vérifiez le schéma de requête du point de terminaison, les références du sponsor requises, les ID d’objet et les valeurs de propriété. |
401 Unauthorized |
Acquérir un jeton d’accès valide pour Microsoft Graph et l’envoyer dans l’en-tête Authorization. |
403 Forbidden |
Vérifiez que l’application de gestion dispose des autorisations déléguées requises et du consentement administrateur, que l’utilisateur connecté est autorisé pour l’opération et que le locataire est activé pour la préversion. |
Pour plus d’informations, consultez les réponses d’erreur de Microsoft Graph. Lorsque vous contactez un administrateur ou le support Microsoft, incluez le code d’état HTTP, le code d’erreur et request-id l’en-tête de réponse. N’incluez pas de jetons d’accès ou d’autres informations d’identification.
Étape suivante
Revenez au tutoriel qui vous a amené ici :
- Authentifiez les utilisateurs à une API de l’agent ASP.NET Core.
- Appelez une API personnalisée comme agent avec ASP.NET Core.
- Configurez le sidecar du SDK d’authentification.
- Connectez des utilisateurs à partir d’un agent sur un appareil utilisateur final.
Pour obtenir des requêtes OAuth directes et le modèle d’identité derrière cette configuration, consultez Authentifier les modes d’instance d’identité de l’agent et d’identité de l’agent.