SKILL: Créer des utilisateurs Agent dans Microsoft Entra Agent ID

Aperçu

Un utilisateur agent est une identité utilisateur spécialisée dans Microsoft Entra ID qui permet aux agents IA d'agir en tant que travailleurs numériques. Cela leur permet d'accéder aux API et services qui exigent strictement des identités utilisateur (par exemple, les boîtes aux lettres Exchange, Teams, les organigrammes), tout en maintenant des limites de sécurité appropriées.

Les utilisateurs agent reçoivent des jetons avec idtyp=user, contrairement aux identités agent régulières qui reçoivent idtyp=app.

Conditions préalables

• Un locataire Microsoft Entra avec les capacités Agent ID
• Une identité agent (principal de service de type ServiceIdentity) créée à partir d'un blueprint d'identité agent
• L'une des permissions suivantes :
  • AgentIdUser.ReadWrite.IdentityParentedBy (privilégié minimal)
  • AgentIdUser.ReadWrite.All
  • User.ReadWrite.All
• L'appelant doit avoir au minimum le rôle Agent ID Administrator (dans les scénarios délégués)

Important: Le identityParentId doit référencer une véritable identité agent (créée via un blueprint d'identité agent), PAS un principal de service d'application régulière. Vous pouvez vérifier que le principal de service dispose de @odata.type: #microsoft.graph.agentIdentity et servicePrincipalType: ServiceIdentity.

Architecture

Blueprint d'identité agent (modèle d'application)
    │
    ├── Identité agent (principal de service - ServiceIdentity)
    │       │
    │       └── Utilisateur agent (utilisateur - agentUser) ← relation 1:1
    │
    └── Principal du blueprint d'identité agent (principal de service dans le locataire)

Étape 1 : Vérifier que l'identité agent existe

Avant de créer un utilisateur agent, confirmez que l'identité agent est du type agentIdentity correct :

GET https://graph.microsoft.com/beta/servicePrincipals/{agent-identity-id}
Authorization: Bearer <token>

Vérifiez que la réponse contient :

{
  "@odata.type": "#microsoft.graph.agentIdentity",
  "servicePrincipalType": "ServiceIdentity",
  "agentIdentityBlueprintId": "<blueprint-id>"
}

PowerShell

Connect-MgGraph -Scopes "Application.Read.All" -TenantId "<tenant>" -UseDeviceCode -NoWelcome
Invoke-MgGraphRequest -Method GET `
  -Uri "https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-id>" | ConvertTo-Json -Depth 3

Erreur courante: Utiliser l'appId d'un enregistrement d'application ou l'id d'un principal de service d'application régulière échouera. Seules les identités agent créées à partir de blueprints fonctionnent.

Étape 2 : Créer l'utilisateur agent

Requête HTTP

POST https://graph.microsoft.com/beta/users/microsoft.graph.agentUser
Content-Type: application/json
Authorization: Bearer <token>

{
  "accountEnabled": true,
  "displayName": "My Agent User",
  "mailNickname": "my-agent-user",
  "userPrincipalName": "my-agent-user@yourtenant.onmicrosoft.com",
  "identityParentId": "<agent-identity-object-id>"
}

Propriétés requises

PowerShell

Connect-MgGraph -Scopes "User.ReadWrite.All" -TenantId "<tenant>" -UseDeviceCode -NoWelcome

$body = @{
  accountEnabled    = $true
  displayName       = "My Agent User"
  mailNickname      = "my-agent-user"
  userPrincipalName = "my-agent-user@yourtenant.onmicrosoft.com"
  identityParentId  = "<agent-identity-object-id>"
} | ConvertTo-Json

Invoke-MgGraphRequest -Method POST `
  -Uri "https://graph.microsoft.com/beta/users/microsoft.graph.agentUser" `
  -Body $body -ContentType "application/json" | ConvertTo-Json -Depth 3

Points clés

• Pas de mot de passe — les utilisateurs agent ne peuvent pas avoir de mots de passe. Ils s'authentifient via les identifiants de leur identité agent parent.
• Relation 1:1 — chaque identité agent peut avoir au maximum un utilisateur agent. La tentative de créer un second retourne 400 Bad Request.
• Le userPrincipalName doit être unique. Ne réutilisez pas l'UPN d'un utilisateur existant.

Étape 3 : Assigner un responsable (Facultatif)

L'assignation d'un responsable permet à l'utilisateur agent d'apparaître dans les organigrammes (par exemple, Teams).

PUT https://graph.microsoft.com/beta/users/{agent-user-id}/manager/$ref
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.id": "https://graph.microsoft.com/beta/users/{manager-user-id}"
}

PowerShell

$managerBody = '{"@odata.id":"https://graph.microsoft.com/beta/users/<manager-user-id>"}'
Invoke-MgGraphRequest -Method PUT `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>/manager/`$ref" `
  -Body $managerBody -ContentType "application/json"

Étape 4 : Définir le lieu d'utilisation et assigner des licences (Facultatif)

Une licence est nécessaire pour que l'utilisateur agent dispose d'une boîte aux lettres, de présence Teams, etc. Le lieu d'utilisation doit être défini en premier.

Définir le lieu d'utilisation

PATCH https://graph.microsoft.com/beta/users/{agent-user-id}
Content-Type: application/json
Authorization: Bearer <token>

{
  "usageLocation": "US"
}

Lister les licences disponibles

GET https://graph.microsoft.com/beta/subscribedSkus?$select=skuPartNumber,skuId,consumedUnits,prepaidUnits
Authorization: Bearer <token>

Nécessite la permission Organization.Read.All.

Assigner une licence

POST https://graph.microsoft.com/beta/users/{agent-user-id}/assignLicense
Content-Type: application/json
Authorization: Bearer <token>

{
  "addLicenses": [
    { "skuId": "<sku-id>" }
  ],
  "removeLicenses": []
}

PowerShell (tout en un)

Connect-MgGraph -Scopes "User.ReadWrite.All","Organization.Read.All" -TenantId "<tenant>" -NoWelcome

# Définir le lieu d'utilisation
Invoke-MgGraphRequest -Method PATCH `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>" `
  -Body '{"usageLocation":"US"}' -ContentType "application/json"

# Assigner une licence
$licenseBody = '{"addLicenses":[{"skuId":"<sku-id>"}],"removeLicenses":[]}'
Invoke-MgGraphRequest -Method POST `
  -Uri "https://graph.microsoft.com/beta/users/<agent-user-id>/assignLicense" `
  -Body $licenseBody -ContentType "application/json"

Conseil: Vous pouvez également assigner des licences via le centre d'administration Entra sous Identity → Users → All users → sélectionner l'utilisateur agent → Licenses and apps.

Temps de provisionnement

Capacités de l'utilisateur agent

• ✅ Ajouté aux groupes Microsoft Entra (y compris les groupes dynamiques)
• ✅ Accès aux API utilisateur uniquement (jetons idtyp=user)
• ✅ Posséder une boîte aux lettres, un calendrier et des contacts
• ✅ Participer à des conversations et des canaux Teams
• ✅ Apparaître dans les organigrammes et la recherche de personnes
• ✅ Ajouté aux unités administratives
• ✅ Licences assignées

Contraintes de sécurité de l'utilisateur agent

• ❌ Impossible d'avoir des mots de passe, des passkeys ou une connexion interactive
• ❌ Impossible d'être assigné à des rôles d'administrateur privilégié
• ❌ Impossible d'être ajouté à des groupes assignables par rôle
• ❌ Permissions similaires aux utilisateurs invités par défaut
• ❌ Assignation de rôle personnalisé non disponible

Dépannage

Références

• Agent identities
• Agent users
• Agent service principals
• Create agent identity blueprint
• Create agent identities
• agentUser resource type (Graph API)
• Create agentUser (Graph API)