Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
I ruoli dell'app definiscono chi può accedere a un agente e cosa può fare. Usale per limitare le operazioni dell'agente a utenti, gruppi o applicazioni client approvate.
In questo articolo si definisce un ruolo di accesso in ingresso, lo si assegna a un chiamante e lo si applica nell'API dell'agente. La posizione in cui si definisce il ruolo dipende dal fatto che l'agente usi un blueprint a istanza singola o una flotta.
Prerequisiti
- Un blueprint e l'entità servizio dell'API dell'agente.
- Client di gestione Microsoft Graph autorizzato per la configurazione del ruolo. Per la gestione delegata di singole istanze, l'utente connesso deve possedere l'identità dell'agente o avere il ruolo Agent ID Administrator. Vedere Update servicePrincipal per le autorizzazioni API applicabili.
- Amministratore applicazione o Amministratore applicazione cloud per gestire le assegnazioni di ruolo dell'app per utenti e gruppi.
-
AppRoleAssignment.ReadWrite.Alle l'autorizzazione di lettura appropriata per le assegnazioni programmatiche.
Per il percorso cloud a istanza singola, l'entità servizio dell'API è l'identità dell'agente, non un'entità principale blueprint. Usare il relativo ID oggetto come <agent-api-service-principal-object-id> nelle richieste contenute in questo articolo. Un progetto a istanza singola non ha un principal del blueprint. Per il viaggio avanzato della flotta, usare invece l'entità blueprint della flotta; le assegnazioni si applicano in tutta la flotta.
Definire i ruoli dell'app
Scegliere la posizione della definizione per la modalità istanza:
| Modalità di istanza | Definire il ruolo in entrata su | Assegnare il ruolo in |
|---|---|---|
| Istanza singola | L'applicazione Blueprint e il service principal dell'ID agente, usando lo stesso GUID del ruolo e lo stesso valore. | L'entità servizio Agent ID. |
| Fleet | Applicazione blueprint. | Il principal del blueprint che rappresenta l'API della flotta. |
Usa un ruolo quando tutti hanno lo stesso livello di accesso. Ad esempio, usare Agent.User per le attività standard e aggiungere Agent.Admin solo se si espongono attività amministrative. Mantenere stabili i valori dei ruoli perché i criteri di autorizzazione li controllano.
Dichiarare il ruolo nel blueprint
Definire Agent.User nella raccolta appRoles dell'applicazione blueprint. Per un agente a istanza singola, completare anche la sezione successiva per rendere disponibile lo stesso ruolo nell'ID agente.
Leggere prima il appRoles esistente del blueprint. La richiesta seguente riguarda un blueprint senza ruoli esistenti. Per una raccolta esistente, includere le definizioni di ruolo esistenti che si intende conservare; l'aggiornamento appRoles sostituisce la raccolta. Omettere il campo origin di sola lettura dalle richieste.
Sostituire <agent-user-role-id> con un nuovo GUID e salvarlo per il passaggio di assegnazione:
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"
}
]
}
Accesso utente a istanza singola
Per un agente a istanza singola, pubblicare lo stesso ruolo utente direttamente nella raccolta appRoles dell'ID agente. Usare lo stesso GUID e il valore della dichiarazione blueprint, non un secondo GUID del ruolo. La dichiarazione del solo blueprint non rende disponibile il ruolo per l'assegnazione nell'ID agente. La definizione solo service principal non completa la configurazione del blueprint usata in questa procedura.
Leggere prima i ruoli esistenti dell'ID agente e conservarne le definizioni nell'aggiornamento. Per un ID agente senza ruoli esistenti, inviare:
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"
}
]
}
Questa è la configurazione del ruolo in due oggetti separati, non l'ereditarietà delle autorizzazioni o una concessione API downstream. Non creare un principal blueprint per un agente a istanza singola.
La definizione dell'entità servizio (service principal) supporta User per utenti e gruppi. Non aggiungere Application a questa richiesta: i ruoli assegnabili alle applicazioni client devono essere definiti in un oggetto applicazione. Questa procedura per singola istanza riguarda l'accesso utente in ingresso, non le applicazioni che chiamano senza utente. Vedere le informazioni di riferimento sulle risorse appRole.
Accesso alla flotta
Per una flotta, usare la dichiarazione blueprint senza l'aggiornamento del service principal a istanza singola. Includere User in allowedMemberTypes per utenti o gruppi e Application per le applicazioni client. Per la procedura a livello di applicazione, vedere Aggiungere ruoli a un'applicazione. Usare l'entità servizio blueprint, non un ID agente figlio, come risorsa per le assegnazioni in entrata.
Verificare il ruolo sul resource principal
Prima di richiedere o assegnare un ruolo, recuperare il blueprint con GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=appRoles e l'API principal dell'agente con GET https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>?$select=appRoles. Usare un client di gestione autorizzato, non il token di runtime dell'agente.
Verificare che il appRoles dell'entità contenga esattamente il id e il value del ruolo, che isEnabled sia true e che allowedMemberTypes includa il tipo di assegnatario previsto.
Se un'assegnazione restituisce Permission being assigned was not found on application, controlla la definizione del ruolo nel principal della risorsa e l'resourceId e il appRoleId dell'assegnazione. Per un agente a istanza singola, completa la definizione diretta sopra se hai definito il ruolo solo nel blueprint. Non creare un principal del blueprint, sostituire un'altra risorsa o rimuovere il controllo del ruolo dell'API. Continuare solo dopo che il principal desiderato espone il ruolo.
Richiedere un'assegnazione di ruolo dell'app
Impostare appRoleAssignmentRequired nell'entità servizio dell'API dell'agente. Quando la proprietà è true, Microsoft Entra ID rilascia un token di accesso per l'API dell'agente solo agli utenti e alle applicazioni assegnati.
PATCH https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>
Content-Type: application/json
Authorization: Bearer <access-token>
{
"appRoleAssignmentRequired": true
}
Per altre informazioni, vedere le informazioni di riferimento sull'API di aggiornamento Microsoft Graph.
Assegnare un ruolo app
Assegnare il ruolo dell'app a un utente nell'entità servizio principale API dell'agente:
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>"
}
Usare il GUID salvato quando è stato definito Agent.User come <app-role-id>. Per un gruppo, creare l'assegnazione tramite le assegnazioni di ruolo dell'app del gruppo. Per un ruolo di flotta che consente Application, creare l'assegnazione di un'applicazione client tramite l'entità servizio del client. In ogni caso, usare l'ID oggetto dell'entità servizio dell'API dell'agente come resourceId.
Applicare i ruoli dell'app nell'API dell'agente
Quando un utente o un'applicazione assegnata ottiene un token di accesso per l'API dell'agente, Microsoft Entra ID include i valori del ruolo app assegnato nell'attestazione del roles token. L'API dell'agente verifica tale claim prima di consentire l'operazione richiesta.
Dopo aver configurato l'autenticazione e la convalida del token, aggiungere un criterio di autorizzazione che richiede il ruolo dell'app:
In Program.cs, unisci la registrazione dei criteri in builder.Services.AddAuthorization prima di builder.Build(). Posizionare il mapping degli endpoint dopo il middleware di autenticazione e autorizzazione e prima di app.Run(); le due parti di questo frammento non sono adiacenti tra loro in un'applicazione completa.
builder.Services.AddAuthorization(options =>
{
options.AddPolicy(
"AgentUser",
policy => policy.RequireRole("Agent.User"));
});
app.MapPost("/tasks", () => Results.Accepted())
.RequireAuthorization("AgentUser");
AddAuthorizationregistra i servizi di autorizzazione ASP.NET Core.
RequireRole controlla se l'identità autenticata ha il ruolo Agent.User. Microsoft.Identity.Web riconosce i ruoli dell'app Microsoft Entra nel claim roles del token di accesso.
Chiamare UseAuthentication prima di UseAuthorization nella pipeline middleware, come illustrato nell'articolo sull'autenticazione. Richiedere un nuovo token di accesso dopo la modifica di un'assegnazione. Durante la risoluzione dei problemi, verificare l'assegnazione nell'entità servizio dell'API agente e l'attestazione roles del token.
Con un nuovo token per l'API dell'agente e il ruolo assegnato Agent.User , l'esempio POST /tasks restituisce 202 Accepted. Senza un token, aspettarsi 401. Un token altrimenti valido senza tale ruolo viene rifiutato se 403 il tenant lo rilascia. Quando è necessaria l'assegnazione, Microsoft Entra ID potrebbe rifiutare l'accesso o il rilascio di token prima che la richiesta raggiunga l'API.