Autenticare gli utenti e acquisire i token per gli agenti interattivi

Gli agenti interattivi eseguono azioni per conto degli utenti. Per agire per conto degli utenti in modo sicuro, l'agente autentica l'utente, ottiene il consenso per le autorizzazioni necessarie e acquisisce i token di accesso per le API downstream. Questo articolo illustra il flusso di autenticazione e acquisizione di token end-to-end per l'agente interattivo:

Concedere autorizzazioni tramite autorizzazioni ereditabili o consenso.
Autenticare l'utente e ottenere un token di accesso.
Convalidare il token ed estrarre le attestazioni utente.
Acquisizione dei token per le API downstream usando il flusso OBO (On-Behalf-Of).

Annotazioni

Questo articolo illustra gli agenti interattivi che agiscono per conto degli utenti connessi usando il flusso OBO. Se l'agente necessita di una propria identità simile all'utente (uno scenario di lavoro digitale), vedere Account utente dell'agente e flusso OAuth dell'account utente dell'agente.

Prerequisiti

Prima di iniziare, assicurati di avere:

Un progetto di identità dell'agente. Registrare l'ID app dello schema dell'identità dell'agente (ID client).
Identità dell'agente.
Un'applicazione client registrata in Microsoft Entra per gestire l'autenticazione utente.
Familiarità con il flusso del codice di autorizzazione OAuth 2.0.
La possibilità di eseguire un'API Web ASP.NET Core se si prevede di usare gli esempi di convalida dei token e OBO in questo articolo.

Per l'autorizzazione dell'amministratore, è anche necessario:

Accesso amministratore per concedere il consenso per le autorizzazioni dell'applicazione.

Prima che l'agente possa agire per conto di un utente, l'utente o un amministratore deve fornire il consenso alle autorizzazioni necessarie. Esistono due approcci per concedere le autorizzazioni:

Autorizzazioni ereditabili: preautorizza le autorizzazioni nel blueprint in modo che le identità degli agenti le ereditino automaticamente.
Richiedi consenso: registrare un URI di reindirizzamento e richiedere agli utenti o agli amministratori di concedere il consenso tramite una richiesta OAuth o usare l'endpoint di consenso amministratore.

Usare autorizzazioni ereditabili

Configura le autorizzazioni ereditabili sul modello di identità dell'agente per preautorizzare un insieme di base di ambiti delegati e ruoli dell'applicazione. Le identità dell'agente create dal progetto ereditano automaticamente tali autorizzazioni senza richieste di consenso interattive. Per altre informazioni, vedi Configurare le autorizzazioni ereditabili per i modelli di identità dell'agente.

Per richiedere il consenso tramite un flusso OAuth, il progetto di identità dell'agente deve prima essere configurato con un URI di reindirizzamento. Per i progetti, l'URI di reindirizzamento deve essere un tipo di applicazione Web . A differenza degli URI di reindirizzamento nelle registrazioni di app, un URI di reindirizzamento in un blueprint non può essere usato per ottenere token di autorizzazione con autorizzazioni delegate. Nella richiesta OAuth2 è supportato solo response_type=none, il che significa che la richiesta registra soltanto il consenso e non viene restituito alcun token.

Per aggiornare l'URI di reindirizzamento del modello di identità dell'agente, è necessario prima ottenere un token di accesso con l'autorizzazione delegata AgentIdentityBlueprint.ReadWrite.All. Invia quindi una richiesta PATCH all'oggetto dell'applicazione per il modello di identità dell'agente:

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

{
  "web": {
    "redirectUris": [
      "https://myagentapp.com/authorize"
    ]
  }
}

Usare Microsoft Graph PowerShell per aggiornare il progetto di identità dell'agente con l'URI di reindirizzamento.

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

$applicationId = "<agent-blueprint-id>"
$web = @{
    redirectUris= @(
        "https://myagentapp.com/authorize"
    )
}

$body = @{
    web   =  $web
}

Invoke-MgGraphRequest -Method PATCH `
        -Uri "https://graph.microsoft.com/beta/applications/$applicationId" `
        -Headers @{ "OData-Version" = "4.0" } `
        -Body ($body | ConvertTo-Json)

Prima che l'agente possa agire per conto di un utente, l'utente deve fornire il consenso alle autorizzazioni necessarie. La richiesta di consenso dell'utente non restituisce un token. Registra invece che l'utente ha concesso all'agente l'autorizzazione ad agire per suo conto. L'acquisizione di token avviene in Autenticare l'utente e richiedere un token.

Importante

Usare l'ID client di identità dell'agente nel client_id parametro e non l'ID progetto identità agente.

Per richiedere il consenso a un utente, creare un URL di autorizzazione e reindirizzarlo all'utente. L'agente può presentare questo URL in modi diversi, ad esempio come collegamento in un messaggio di chat.

https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/authorize?
  client_id=<agent-identity-id>
  &response_type=none
  &redirect_uri=https%3A%2F%2Fmyagentapp.com%2Fauthorize
  &response_mode=query
  &scope=User.Read
  &state=xyz123

Quando l'utente apre questo URL, Microsoft Entra ID richiede di accedere e concedere il consenso. Dopo il consenso, l'utente viene inviato di nuovo all'URI di reindirizzamento.

I parametri chiave nell'URL di autorizzazione del consenso utente sono:

client_id: ID client dell'identità dell'agente (non l'ID client del modello di identità dell'agente).
response_type: impostato su none perché questa richiesta registra solo il consenso. L'acquisizione di token usa response_type=code in Autenticare l'utente e richiedere un token.
redirect_uri: deve corrispondere esattamente all'URI di reindirizzamento configurato nel progetto di identità dell'agente.
scope: specificare le autorizzazioni delegate necessarie, ad esempio User.Read.
state: parametro facoltativo per mantenere lo stato tra la richiesta e il callback.

Per altre informazioni sui concetti relativi all'autorizzazione OAuth, consultare Autorizzazioni e consenso nella Microsoft Identity Platform.

Gli agenti possono anche richiedere l'autorizzazione da un amministratore Microsoft Entra ID, che può concedere il consenso all'agente per tutti gli utenti nel tenant. Il consenso amministratore potrebbe essere necessario a seconda delle impostazioni di consenso configurate nel tenant.

Per concedere il consenso amministratore a livello di tenant, indirizzare un amministratore all'URL seguente. Usare l'ID dell'identità dell'agente nel parametro client_id.

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-id>
&scope=User.Read
&redirect_uri=<redirect-uri>
&state=xyz123

Dopo che l'amministratore concede il consenso, le autorizzazioni si applicano all'intero tenant. Gli utenti non devono più fornire il consenso.

Annotazioni

Configurare un URI di reindirizzamento nel progetto e includere un state parametro nella richiesta di consenso. Quando viene concesso il consenso, l'utente viene inviato all'URI di reindirizzamento in cui è possibile visualizzare la conferma. L'endpoint può usare il state parametro per tenere traccia dell'autorizzazione concessa. Per gli agenti a tenant singolo, è possibile ripetere in alternativa le richieste di token fino a quando non viene concesso il consenso perché l'ID tenant è già noto.

Autenticare l'utente e richiedere un token

Dopo aver concesso il consenso, l'app client (ad esempio un front-end o un'app per dispositivi mobili) avvia una richiesta di codice di autorizzazione OAuth 2.0 per ottenere un token in cui il gruppo di destinatari è il progetto di identità dell'agente. In questo passaggio, client_id si riferisce all'ID applicativo registrato dell'app client stessa, non all'identità dell'agente o al modello di identità dell'agente.

Annotazioni

L'redirect_uri in questa richiesta appartiene alla registrazione dell'app client, non all'URI di reindirizzamento del blueprint configurato nel precedente passaggio di consenso.

Reindirizzare l'utente all'endpoint di autorizzazione Microsoft Entra ID con i parametri seguenti:

GET https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/authorize?client_id=<client-app-id>
&response_type=code
&redirect_uri=<redirect_uri>
&response_mode=query
&scope=api://<agent-blueprint-id>/access_agent
&state=abc123

Dopo l'accesso dell'utente, l'app riceve un codice di autorizzazione nell'URI di reindirizzamento. Scambia il codice di autorizzazione con un token di accesso:
```
POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<client-app-id>
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<redirect_uri>
&scope=api://<agent-blueprint-id>/access_agent
&client_secret=<client-secret>
```
Includere il client_secret parametro solo se si usa un client riservato.

La risposta JSON contiene un token di accesso che può essere usato per accedere all'API dell'agente.

Convalidare il token di accesso

L'API Web deve convalidare il token di accesso in ingresso prima che l'agente possa agire. Usare sempre una libreria approvata per convalidare i token. Non scrivere codice personalizzato per la convalida dei token.

Installare il pacchetto NuGet Microsoft.Identity.Web:
```
dotnet add package Microsoft.Identity.Web
```

Nel progetto API Web di ASP.NET Core implementare l'autenticazione Microsoft Entra ID:

// Program.cs
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

Configurare le credenziali di autenticazione nel appsettings.json file:

Avvertimento

I segreti client non devono essere usati come credenziali client negli ambienti di produzione per i progetti di identità agente a causa di rischi per la sicurezza. Usare invece metodi di autenticazione più sicuri, ad esempio le credenziali di identità federate (FIC) con identità gestite o certificati client. Questi metodi offrono una sicurezza avanzata eliminando la necessità di archiviare segreti sensibili direttamente all'interno della configurazione dell'applicazione.
```
"AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<my-test-tenant>",
    "ClientId": "<agent-blueprint-id>",
    "Audience": "<agent-blueprint-id>",
    "ClientCredentials": [
        {
            "SourceType": "ClientSecret",
            "ClientSecret": "your-client-secret"
        }
    ]
}
```

Per altre informazioni sulle Microsoft. Identity.Web, vedere Microsoft. Documentazione di Identity.Web.

Convalidare le attestazioni utente

Dopo la convalida del token di accesso, l'agente può identificare l'utente ed eseguire i controlli di autorizzazione. La route API di esempio seguente estrae le attestazioni utente dal token di accesso e le restituisce nella risposta dell'API:

app.MapGet("/hello-agent", (HttpContext httpContext) =>
{   
    var claims = httpContext.User.Claims.Select(c => new
    {
        Type = c.Type,
        Value = c.Value
    });

    return Results.Ok(claims);
})
.RequireAuthorization();

Acquisire i token per le API downstream

Dopo che un agente interattivo convalida il token dell'utente, può richiedere token di accesso per chiamare le API downstream per conto dell'utente. Il flusso On-Behalf-Of (OBO) consente all'agente di:

Ricevere un token di accesso da un client.
Esegui lo scambio per un nuovo token di accesso per un'API downstream come Microsoft Graph.
Usare il nuovo token per accedere alle risorse protette per conto dell'utente originale.

Use Microsoft Identity Web
Use Microsoft Graph SDK

La libreria Microsoft.Identity.Web semplifica l'implementazione OBO gestendo automaticamente lo scambio di token, quindi non è necessario implementare manualmente il flusso seguendo il protocollo.

Installare i pacchetti NuGet necessari:

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.AgentIdentities

Nel progetto API Web ASP.NET Core aggiornare l'implementazione dell'autenticazione Microsoft Entra ID:

// Program.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

Nell'API dell'agente scambiare il token di accesso utente in ingresso per un nuovo token di accesso per l'identità dell'agente. Microsoft.Identity.Web convalida il token di accesso in ingresso e gestisce lo scambio di token per conto di altri:

app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";
    IAuthorizationHeaderProvider authorizationHeaderProvider = httpContext.RequestServices.GetService<IAuthorizationHeaderProvider>()!;
    AuthorizationHeaderProviderOptions options = new AuthorizationHeaderProviderOptions().WithAgentIdentity(agentIdentity);

    string authorizationHeaderWithUserToken = await authorizationHeaderProvider.CreateAuthorizationHeaderForUserAsync(["https://graph.microsoft.com/.default"], options);

    var response = new { header = authorizationHeaderWithUserToken };
    return Results.Json(response);
})
.RequireAuthorization();

Se si usa Microsoft Graph SDK, è possibile eseguire l'autenticazione per Microsoft Graph usando il GraphServiceClient.

Installare i pacchetti NuGet necessari:

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.AgentIdentities
dotnet add package Microsoft.Identity.Web.GraphServiceClient

Nel progetto API Web ASP.NET Core configurare l'autenticazione e aggiungere il supporto per Microsoft Graph:

// Program.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();
builder.Services.AddMicrosoftGraph();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.Run();

Ottieni un GraphServiceClient dal provider di servizi e chiama le API Microsoft Graph con l'identità dell'agente:

app.MapGet("/agent-obo-user", async (HttpContext httpContext) =>
{
    string agentIdentity = "<your-agent-identity>";

    GraphServiceClient graphServiceClient = httpContext.RequestServices.GetService<GraphServiceClient>()!;
    var me = await graphServiceClient.Me.GetAsync(r => r.Options.WithAuthenticationOptions(
        o =>
        {
            o.WithAgentIdentity(agentIdentity);
        }));
    return me.UserPrincipalName;
})
.RequireAuthorization();

Dietro le quinte, il flusso OBO prevede due scambi di token: prima, il modello di identità dell'agente ottiene un token di conversione usando le credenziali client e, quindi, l'identità dell'agente scambia tale token insieme al token di accesso dell'utente per un token API downstream. Per la procedura dettagliata completa del protocollo, inclusi i formati di richiesta HTTP e i dettagli di convalida dei token, consultare il flusso delegato negli agenti.

Altre informazioni sui token dell'agente e sulle API correlate:

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-06-15

Autenticare gli utenti e acquisire i token per gli agenti interattivi

Prerequisiti

Autorizzazioni e consenso

Usare autorizzazioni ereditabili

Richiesta consenso

Registrare un URI di reindirizzamento

Richiedere il consenso dell'utente

Richiedere il consenso amministratore per tutti gli utenti

Autenticare l'utente e richiedere un token

Convalidare il token di accesso

Convalidare le attestazioni utente

Acquisire i token per le API downstream

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive