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.
Les rôles d’application définissent qui peut accéder à un agent et les actions qu’ils peuvent effectuer. Utilisez-les pour restreindre les opérations de l’agent aux utilisateurs, groupes ou applications clientes approuvées.
Dans cet article, vous définissez un rôle d’accès entrant, affectez-le à un appelant et appliquez-le dans l’API de l’agent. L’emplacement où vous définissez le rôle dépend du fait que l’agent utilise un blueprint à instance unique ou une flotte.
Prerequisites
- Un blueprint et son principal du service d’API agent.
- Un client de gestion Microsoft Graph autorisé pour la configuration des rôles. Pour la gestion d’instance unique déléguée, l’utilisateur connecté doit posséder l’identité de l’agent ou avoir le rôle Administrateur d’ID d’agent . Consultez Update servicePrincipal pour connaître les autorisations d’API applicables.
- Administrateur d’application ou Administrateur d’application cloud pour gérer les attributions de rôles d’application d’utilisateur et de groupe.
-
AppRoleAssignment.ReadWrite.Allet l’autorisation de lecture appropriée pour les affectations par programmation.
Pour le parcours cloud à instance unique, le principal de service de l’API est l’identité de l’agent, et non un principal de blueprint. Utilisez son ID d’objet comme <agent-api-service-principal-object-id> dans les requêtes de cet article. Un blueprint à instance unique n’a pas de principal de blueprint. Pour le parcours avancé de la flotte, utilisez plutôt le principal blueprint de la flotte ; ses affectations s’appliquent à l’ensemble de la flotte.
Définir des rôles d’application
Choisissez l’emplacement de définition de votre mode d’instance :
| Mode d’instance | Définir le rôle d’entrée sur | Attribuer le rôle sur |
|---|---|---|
| instance unique | L’application Blueprint et le principal de service Agent ID, utilisant le même GUID de rôle et la même valeur. | Principal du service ID de l’agent. |
| Fleet | Le schéma de l’application. | Le principal du blueprint qui représente l’API de flotte. |
Utilisez un rôle lorsque tout le monde a le même niveau d’accès. Par exemple, utilisez Agent.User pour les tâches standard et ajoutez Agent.Admin uniquement si vous exposez des tâches administratives. Conservez les valeurs des rôles inchangées, car vos politiques d’autorisation les vérifient.
Déclarer le rôle dans le plan
Définissez Agent.User dans la collection appRoles de l’application blueprint. Pour un agent à instance unique, terminez également la section suivante pour rendre le même rôle disponible sur son ID d’agent.
Lisez d’abord les éléments existants du blueprint appRoles. La requête suivante concerne un blueprint sans rôles existants. Pour une collection existante, incluez les définitions de rôle existantes que vous envisagez de conserver ; la mise à jour appRoles remplace la collection. Omettez le champ en lecture seule origin des requêtes.
Remplacez <agent-user-role-id> par un nouveau GUID et enregistrez-le pour l’étape d’affectation :
PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
Content-Type: application/json
Authorization: Bearer <management-access-token>
{
"@odata.type": "#microsoft.graph.agentIdentityBlueprint",
"appRoles": [
{
"id": "<agent-user-role-id>",
"allowedMemberTypes": ["User"],
"description": "Use standard agent features",
"displayName": "Agent user",
"isEnabled": true,
"value": "Agent.User"
}
]
}
Accès utilisateur à une instance unique
Pour un agent à instance unique, publiez le même rôle d’utilisateur directement dans la collection de l’ID d’agent appRoles. Utilisez le même GUID et la même valeur que dans la déclaration du blueprint, pas un deuxième GUID de rôle. La déclaration blueprint uniquement ne rend pas le rôle disponible pour l’attribution sur l’ID de l’agent. La définition de service-principal uniquement ne complète pas la configuration du blueprint utilisée dans cette procédure.
Consultez d’abord les rôles existants de l’ID d’agent et conservez leurs définitions lors de la mise à jour. Pour un ID d’agent sans rôles existants, envoyez :
PATCH https://graph.microsoft.com/beta/servicePrincipals/<agent-api-service-principal-object-id>
Content-Type: application/json
Authorization: Bearer <management-access-token>
{
"appRoles": [
{
"id": "<agent-user-role-id>",
"allowedMemberTypes": ["User"],
"description": "Use standard agent features",
"displayName": "Agent user",
"isEnabled": true,
"value": "Agent.User"
}
]
}
Il s’agit d’une configuration de rôle sur deux objets distincts, et non sur l’héritage des autorisations ou un octroi d’API en aval. Ne créez pas de principal de blueprint pour un agent à instance unique.
La définition du principal de service prend en charge User pour les utilisateurs et les groupes. N’ajoutez Application pas à cette requête : les rôles assignables aux applications clientes doivent être définis sur un objet d’application. Cette procédure à instance unique couvre l’accès des utilisateurs entrants, et non les appelants sans utilisateur. Consultez la référence de ressource appRole.
Accès à la flotte
Pour une flotte, utilisez la déclaration du modèle sans la mise à jour du principal de service monoinstance. Incluez User dans allowedMemberTypes pour les utilisateurs ou les groupes et Application pour les applications clientes. Pour connaître la procédure au niveau de l’application, consultez Ajouter des rôles d’application à une application. Utilisez le principal de blueprint, et non un ID d’agent enfant, comme ressource pour les affectations entrantes.
Vérifier le rôle sur le principal de ressource
Avant d’exiger ou d’attribuer un rôle, lisez le blueprint avec GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=appRoles et le principal de l’API de l’agent avec GET https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>?$select=appRoles. Utilisez un client de gestion autorisé, et non le jeton d’exécution de l’agent.
Vérifiez que le appRoles du principal contient les id et value exacts du rôle, que isEnabled est true, et que allowedMemberTypes inclut le type de bénéficiaire prévu.
Si une affectation renvoie Permission being assigned was not found on application, vérifiez la définition de rôle sur le principal de ressource et les resourceId et appRoleId de l’affectation. Pour un agent à instance unique, terminez la définition directe ci-dessus si vous avez défini le rôle uniquement sur le blueprint. Ne créez pas de principal de blueprint, remplacez-la par une autre ressource ou supprimez la vérification du rôle de l’API. Continuez uniquement une fois que le principal prévu expose le rôle.
Exiger une attribution de rôle d’application
Définissez appRoleAssignmentRequired sur le principal du service d’API de l’agent. Lorsque la propriété est true, Microsoft Entra ID émet un jeton d’accès pour l’API de l’agent uniquement aux utilisateurs et applications affectés.
PATCH https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>
Content-Type: application/json
Authorization: Bearer <access-token>
{
"appRoleAssignmentRequired": true
}
Pour plus d’informations, consultez la référence de l’API de mise à jour Microsoft Graph.
Attribuer un rôle d’application
Attribuez le rôle d’application à un utilisateur sur le principal de service de l’API agent :
POST https://graph.microsoft.com/v1.0/users/<user-object-id>/appRoleAssignments
Content-Type: application/json
Authorization: Bearer <access-token>
{
"principalId": "<user-object-id>",
"resourceId": "<agent-api-service-principal-object-id>",
"appRoleId": "<app-role-id>"
}
Utilisez le GUID enregistré lorsque vous avez défini Agent.User en tant que <app-role-id>. Pour un groupe, créez l’attribution via les attributions de rôle d’application du groupe. Pour un rôle de flotte qui autorise Application, créez l’affectation de rôle d’une application cliente par l’intermédiaire du principal de service de ce client. Dans tous les cas, utilisez l’ID d’objet du principal de service de l’agent API comme resourceId.
Imposer des rôles d’application dans l’API de l’agent
Lorsqu'un utilisateur affecté ou une application affectée obtient un jeton d'accès pour l'API de l'agent, Microsoft Entra ID inclut les valeurs de rôle d'application affectées dans la revendication du jeton roles. L’API de l’agent vérifie cette revendication avant d’autoriser l’opération demandée.
Après avoir configuré l’authentification et la validation des jetons, ajoutez une stratégie d’autorisation qui nécessite le rôle d’application :
Dans Program.cs, fusionnez l’enregistrement de la stratégie dans builder.Services.AddAuthorization avant builder.Build(). Placez le mappage de point de terminaison après l’intergiciel d’authentification et d’autorisation et avant app.Run(); les deux parties de ce fragment ne sont pas adjacentes dans une application complète.
builder.Services.AddAuthorization(options =>
{
options.AddPolicy(
"AgentUser",
policy => policy.RequireRole("Agent.User"));
});
app.MapPost("/tasks", () => Results.Accepted())
.RequireAuthorization("AgentUser");
AddAuthorizationinscrit les services d’autorisation ASP.NET Core.
RequireRole vérifie l’identité authentifiée pour le Agent.User rôle. Microsoft.Identity.Web reconnaît les rôles d’application Microsoft Entra dans la revendication roles du jeton d’accès.
Appelez UseAuthentication avant UseAuthorization dans le pipeline middleware, comme indiqué dans l’article d’authentification. Demandez un nouveau jeton d’accès après avoir modifié une affectation. Lors de la résolution des problèmes, vérifiez l’affectation sur le principal du service d’API de l’agent et la revendication roles du jeton.
Avec un nouveau jeton pour l’API de l’agent et le rôle attribué Agent.User , l’exemple POST /tasks retourne 202 Accepted. Sans jeton, attendez-vous à 401 ; un jeton sinon valide sans ce rôle est rejeté avec 403 si le locataire l’émet. Lorsque l’affectation est requise, Microsoft Entra ID peut rejeter la connexion ou l’émission d’un jeton avant que la demande atteigne votre API.