Autenticare gli utenti in agenti interattivi

Gli agenti spesso devono eseguire azioni per conto degli utenti che usano l'agente. Il primo passaggio per creare un agente interattivo consiste nell'autenticare l'utente. Questo articolo illustra il processo di creazione di un semplice servizio Web che autentica un utente. Il progetto di identità dell'agente viene usato per proteggere il servizio Web. La procedura include i passaggi seguenti:

1. Un cliente ottiene un token di accesso con ambito definito per il blueprint dell'identità dell'agente.
2. Convalidare il token nell'API dell'agente.
3. Estrarre attestazioni sull'utente che possono essere usate per l'autorizzazione.

Prerequisiti

Schemi di identità dell'agente. Registrare l'ID app dello schema dell'identità dell'agente (ID client).

Richiedere un token per il progetto di identità dell'agente

Per autenticare un utente, l'app client ,ad esempio un front-end o un'app per dispositivi mobili, deve avviare una richiesta di autorizzazione OAuth 2.0 per ottenere un token in cui il gruppo di destinatari è il progetto di identità dell'agente.

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

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

2. Dopo l'accesso dell'utente, l'app riceve un codice di autorizzazione all'URI di reindirizzamento. Si scambia per 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-id>
   &grant_type=authorization_code
   &code=<authorization_code>
   &redirect_uri=<redirect_uri>
   &scope=api://<agent-blueprint-id>/access_agent
   &client_secret=<client-secret>  # Only if using a confidential client
   

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

Convalidare il token nell'API dell'agente

L'agente, in genere esposto tramite un'API Web, deve convalidare il token di accesso. Usare sempre una libreria approvata per eseguire la convalida dei token e non implementare mai il proprio codice di convalida del token.

1. Installare il Microsoft.Identity.Web pacchetto NuGet:

   dotnet add package Microsoft.Identity.Web
   

2. Nel progetto API Web di ASP.NET Core implementare l'autenticazione di 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();
   

3. Configurare le credenziali di autenticazione nel file appsettings.json :

"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 su Microsoft.Identity.Web, vedere la documentazione ufficiale.

Convalidare le attestazioni utente

Dopo aver convalidato il token di accesso, l'agente può ora identificare l'utente ed eseguire i controlli di autorizzazione. Questa route API di esempio 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();

Contenuti correlati

Dichiarazioni di token