Créer un blueprint d’identité d’agent

Un schéma d’identité d’agent est utilisé pour créer des identités d’agent et demander des jetons à l’aide de ces identités d’agent. Ce guide vous guide tout au long de la création d’un blueprint d’identité d’agent à l’aide de l’API REST Microsoft Graph et de Microsoft Graph PowerShell.

Prerequisites

Avant de créer votre blueprint d’identité d’agent, vérifiez que vous disposez des points suivants :

comprendre les plans d’identité de l’agent
Administrateur de rôle privilégié requis pour accorder des autorisations
L’un des rôles suivants requis pour créer un blueprint : Développeur d’ID d’agent ou administrateur d’ID d’agent. Préférez le rôle Administrateur d’ID d’agent.

Autoriser un client à créer des blueprints d’identité d’agent

Dans cet article, vous utilisez Microsoft Graph PowerShell ou un autre client pour créer votre blueprint d’identité d’agent. Vous devez autoriser ce client à créer un blueprint d’identité d’agent. Le client nécessite l’une des autorisations Microsoft Graph suivantes :

AgentIdentityBlueprint.Create (autorisation déléguée)
AgentIdentityBlueprint.Create (autorisation d’application)

Seul un administrateur général ou un administrateur de rôle privilégié est en mesure d’accorder ces autorisations au client. Pour accorder ces autorisations, un administrateur peut :

Utilisez la commande Connect-MgGraph.
Exécutez un script pour créer un oAuth2PermissionGrant ou appRoleAssignment dans le client.

Créer un blueprint d’identité d’agent

La création d’un blueprint d’identité d’agent fonctionnel dans votre locataire nécessite deux étapes :

Créez un tenant AgentIdentityBlueprint.
Créez un AgentIdentityBlueprintPrincipal dans le client.

Le principal créé dans ce cas est différent de l’identité de l’agent utilisée par l’agent.

API Microsoft Graph
Microsoft Graph PowerShell

Commencez par obtenir un jeton d’accès avec l’autorisation AgentIdentityBlueprint.Create. Une fois que vous avez un jeton d’accès, effectuez la requête suivante.

Conseil / Astuce

Incluez toujours l’en-tête OData-Version lors de l’utilisation @odata.type.

POST https://graph.microsoft.com/beta/applications/
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
  "displayName": "My Agent Identity Blueprint",
  "sponsors@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/<id>",
  ],
	"owners@odata.bind": [
	  "https://graph.microsoft.com/v1.0/users/<id>"
	]
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.Create","User.Read" -TenantId <your-tenant>

# Get the current user's ID
$currentUser = Get-MgContext | Select-Object -ExpandProperty Account
$user = Get-MgUser -UserId $currentUser

Write-Host "Current user: $($user.DisplayName) ($($user.Id))"

# Construct the body for the POST request
$body = @{
    "@odata.type" = "Microsoft.Graph.AgentIdentityBlueprint"
    "displayName" = "My Agent Identity Blueprint"
    "sponsors@odata.bind" = @("https://graph.microsoft.com/v1.0/users/$($user.Id)")
    "owners@odata.bind" = @("https://graph.microsoft.com/v1.0/users/$($user.Id)")
} | ConvertTo-Json -Depth 5

# Make the POST request to create the agent identity blueprint application
$response = Invoke-MgGraphRequest `
    -Method POST `
    -Uri "https://graph.microsoft.com/beta/applications/graph.agentIdentityBlueprint" `
    -Body $body `
    -ContentType "application/json"

# Output the response
$response

Après avoir créé un modèle d’identité d’agent, enregistrez l’identifiant pour les prochaines étapes du guide. Ensuite, créez un principal de service pour votre blueprint d’identité d’agent :

API Microsoft Graph
Microsoft Graph PowerShell

Pour créer le principal de service, vous devez tout d'abord obtenir un jeton d'accès avec l’autorisation AgentIdentityBlueprint.Create. Une fois que vous avez un jeton d’accès, effectuez la requête suivante :

Conseil / Astuce

Incluez toujours l’en-tête OData-Version lors de l’utilisation @odata.type.

POST https://graph.microsoft.com/beta/serviceprincipals/graph.agentIdentityBlueprintPrincipal
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

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

Connect-MgGraph -Scopes "AgentIdentityBlueprintPrincipal.Create" -TenantId <your-test-tenant>
$body = @{
    appId   = "<agent-blueprint-client-id>"
}
Invoke-MgGraphRequest -Method POST `
        -Uri "https://graph.microsoft.com/beta/serviceprincipals/graph.agentIdentityBlueprintPrincipal" `
        -Headers @{ "OData-Version" = "4.0" } `
        -Body ($body | ConvertTo-Json)

Configurer les identifiants pour le modèle d’identité de l’agent

Pour demander des jetons d’accès à l’aide du plan d’identité de l’agent, vous devez ajouter un identifiant client. Nous vous recommandons d'utiliser une identité gérée comme justificatif d'identité fédérée pour les déploiements de production. Pour le développement et les tests locaux, utilisez un secret client.

Ajoutez une identité managée en tant qu'identifiant à l’aide de la requête suivante :

API Microsoft Graph
Microsoft Graph PowerShell

Pour envoyer cette demande, vous devez d’abord obtenir un jeton d’accès avec l’autorisation AgentIdentityBlueprint.AddRemoveCreds.All.

POST https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>/federatedIdentityCredentials
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "name": "my-msi",
    "issuer": "https://login.microsoftonline.com/<my-test-tenant-id>/v2.0",
    "subject": "<msi-principal-id>",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All" -TenantId <your-test-tenant>

$applicationId = "<agent-blueprint-object-id>"

$federatedCredential = @{
  Name             = "my-msi"
  Issuer           = "https://login.microsoftonline.com/<my-test-tenant-id>/v2.0"
  Subject          = "<msi-principal-id>"
  Audiences         = @("api://AzureADTokenExchange")
}

New-MgApplicationFederatedIdentityCredential `
  -ApplicationId $applicationId `
  -BodyParameter $federatedCredential

Dans certains locataires, d’autres types d’informations d’identification d’application, notamment keyCredentials, passwordCredentials et trustedSubjectNameAndIssuers sont également pris en charge. Ces types d’informations d’identification ne sont pas recommandés pour la production, mais peuvent être pratiques pour le développement et les tests locaux. Pour ajouter des identifiants de mot de passe :

API Microsoft Graph
Microsoft Graph PowerShell

Pour envoyer cette demande, vous devez d’abord obtenir un jeton d’accès avec l’autorisation déléguée AgentIdentityBlueprint.AddRemoveCreds.All

POST https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>/addPassword
Content-Type: application/json
Authorization: Bearer <token>

{
  "passwordCredential": {
    "displayName": "My Secret",
    "endDateTime": "2026-08-05T23:59:59Z"
  }
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.AddRemoveCreds.All" -TenantId <your-tenant>

$applicationId = "<agent-blueprint-object-id>"

# Define the secret properties
$displayName = "My Secret"
$endDate = (Get-Date).AddYears(1).ToString("o")  # 1 year from now, in ISO 8601 format

# Construct the password credential
$passwordCredential = @{
    displayName = $displayName
    endDateTime = $endDate
}

# Add the password (client secret)
$response = Add-MgApplicationPassword -ApplicationId $applicationId -PasswordCredential $passwordCredential

# Output the generated secret (only returned once!)
Write-Host "Secret Text: $($response.secretText)"

Veillez à stocker en toute sécurité la passwordCredential valeur générée. Il ne peut pas être consulté après la création initiale. Vous pouvez également utiliser des certificats clients comme informations d’identification ; voir Ajouter des informations d’identification de certificat.

Configurer l’URI et l’étendue de l’identificateur

Pour recevoir des demandes entrantes des utilisateurs et d’autres agents, vous devez définir un URI d’identificateur et une étendue OAuth pour votre blueprint d’identité d’agent :

API Microsoft Graph
Microsoft Graph PowerShell

Pour envoyer cette demande, vous devez d’abord obtenir un jeton d’accès avec l’autorisation AgentIdentityBlueprint.ReadWrite.All.

PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "identifierUris": ["api://<agent-blueprint-id>"],
    "api": {
      "oauth2PermissionScopes": [
        {
          "adminConsentDescription": "Allow the application to access the agent on behalf of the signed-in user.",
          "adminConsentDisplayName": "Access agent",
          "id": "<generate-a-guid>",
          "isEnabled": true,
          "type": "User",
          "value": "access_agent"
        }
      ]
  }
}

Connect-MgGraph -Scopes "AgentIdentityBlueprint.ReadWrite.All" -TenantId <your-tenant>

$AppId = "<agent-blueprint-object-id>"
$IdentifierUri = "api://<agent-blueprint-id>"
$ScopeId = [guid]::NewGuid()

# Construct the OAuth2 permission scope
$scope = @{
    adminConsentDescription = "Allow the application to access the agent on behalf of the signed-in user."
    adminConsentDisplayName = "Access agent"
    id = $ScopeId
    isEnabled = $true
    type = "User"
    value = "access_agent"
}

Update-MgApplication -ApplicationId $AppId `
    -IdentifierUris @($IdentifierUri) `
    -Api @{ oauth2PermissionScopes = @($scope) }

Créer et supprimer des identités d’agent

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-11-19

Partager via

Créer un blueprint d’identité d’agent

Prerequisites

Autoriser un client à créer des blueprints d’identité d’agent

Créer un blueprint d’identité d’agent

Configurer les identifiants pour le modèle d’identité de l’agent

Configurer l’URI et l’étendue de l’identificateur

Contenu connexe

Commentaires

Ressources supplémentaires