Autenticare gli utenti a un'API dell'agente ASP.NET Core

Un client upstream autentica l'utente e invia un token di accesso all'API dell'agente. Questo articolo configura l'API dell'agente ASP.NET Core per convalidare tale token e mostra un client di test locale che accede a un utente e chiama /whoami.

L'autenticazione stabilisce l'identità del chiamante. Il controllo dell'accesso degli utenti agli agenti separatamente determina se tale identità può richiamare l'agente.

Prerequisites

  • Completamento della procedura Creare un'identità per l'agente, inclusi l'abilitazione del tenant e l'handoff dell'amministratore. Registrare l'ID client condiviso e l'ID oggetto dell'identità dell'agente.
  • .NET 10 SDK. Gli esempi usano Microsoft.Identity.Web 4.17.0.
  • Applicazione client upstream che può consentire agli utenti di accedere e richiedere un token di accesso per l'API dell'agente o l'autorizzazione per registrare il client di test locale.
  • Per il passaggio di consenso dell'anteprima, usare il client di gestione con consenso dell'amministratore per l'autorizzazione delegata Graph aggiuntiva DelegatedPermissionGrant.ReadWrite.All. Usare un amministratore autorizzato a fornire il consenso a queste autorizzazioni delegate. Scegliere il ruolo supportato con privilegi minimi da Concedi il consenso amministratore a livello di tenant e confermare eventuali requisiti di consenso in anteprima aggiuntivi con il rappresentante Microsoft.
  • Certificato di sviluppo HTTPS locale attendibile per i test locali. Eseguire dotnet dev-certs https --trust e approvare la richiesta di attendibilità nel computer di sviluppo. Non disabilitare la verifica del certificato.

Registrare un client di test locale

Ignora questa sezione se si dispone già di un client che fa accedere gli utenti e chiama l'agente. Questo client di test è una registrazione di app separata e normale, non un'altra identità dell'agente.

  1. Registrate un'applicazione a tenant singolo denominata client di test dell'API Agent nel tenant dell'agente.
  2. In Autenticazione aggiungere la piattaforma applicazioni per dispositivi mobili e desktop con URI http://localhostdi reindirizzamento. Non è necessario alcun client secret.
  3. Registrare l'ID applicazione (client). In Applicazioni aziendali trovare l'applicazione corrispondente e registrarne l'ID oggetto. Le richieste di token usano l'ID client; le concessioni di consenso usano l'ID oggetto dell'applicazione aziendale.

Il client usa un browser e PKCE. Il reindirizzamento di loopback riceve localmente la risposta di autorizzazione; le chiamate API usano ancora HTTPS.

Configurare l'autorizzazione autorizzata

Il client upstream richiede un'autorizzazione delegata per chiamare l'API dell'agente per l'utente connesso.

  1. Nel blueprint, esporre un URI identificatore e un ambito delegato. Usare access_agent come valore di ambito per questa procedura dettagliata. Mantenere gli ambiti esistenti e impostare api.requestedAccessTokenVersion su 2.
  2. Dichiarare l'ambito nel client requiredResourceAccess upstream. Usare l'ID client dell'agente condiviso come resourceAppId e il GUID dell'ambito esposto con "type": "Scope".
  3. Concedi al client upstream l'accesso per l'utente di test come descritto nella sezione successiva. Durante l'anteprima, il consenso del browser non supporta un'identità dell'agente come risorsa.

Per altre informazioni, vedere Configurare un'applicazione client per accedere a un'API web e Autorizzazioni e consenso in Microsoft Identity Platform.

Configurare il client upstream seguendo il flusso di autenticazione per tale tipo di client. Ad esempio, vedere il flusso del codice di autorizzazione OAuth 2.0. Richiedere l'ambito API dell'agente completamente qualificato:

api://<agent-client-id>/access_agent

Usare una libreria di autenticazione nel client upstream. Non inviare token ID o codici di autorizzazione all'API dell'agente.

Concedi al client upstream l'accesso

Usare il client di gestione per queste richieste di Microsoft Graph, non la credenziale di runtime dell'agente. Questa concessione autorizza il client upstream a chiamare l'agente; non concede all'agente l'accesso alle API downstream.

Prima di eseguire le richieste, aprire la registrazione dell'app di gestione in Interfaccia di amministrazione di Microsoft Entra. In Autorizzazioni API selezionare Aggiungi un'autorizzazione>Microsoft Graph>Autorizzazione delegata, aggiungere DelegatedPermissionGrant.ReadWrite.All e fare in modo che un amministratore autorizzato conceda il consenso. Mantenere le due autorizzazioni di gestione del provisioning. Non aggiungere queste autorizzazioni all'agente o al client di test.

Riconnettiti con tutti e tre gli scope per i quali è stato fornito il consenso:

Disconnect-MgGraph
Connect-MgGraph -ClientId "<management-app-client-id>" `
    -TenantId "<tenant-id>" `
    -Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All", "DelegatedPermissionGrant.ReadWrite.All" `
    -ContextScope Process

Usare Invoke-MgGraphRequest come illustrato in Configurare il client di gestione.

  1. Verificare la presenza di una concessione applicabile esistente:

    GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq '<upstream-client-service-principal-object-id>' and resourceId eq '<agent-identity-object-id>'
    

    Segui la paginazione. Una concessione a livello di tenant applicabile o una concessione per l'utente di test potrebbe già includere access_agent.

  2. Se non esiste alcuna concessione applicabile, concedere l'accesso per l'utente che accederà:

    POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
    Content-Type: application/json
    
    {
      "clientId": "<upstream-client-service-principal-object-id>",
      "resourceId": "<agent-identity-object-id>",
      "consentType": "Principal",
      "principalId": "<user-object-id>",
      "scope": "access_agent"
    }
    

    clientId e resourceId sono ID oggetto dei service principal, non ID client di OAuth. Se per tale utente esiste già una concessione, ma manca l'ambito, aggiornare l'ambito della concessione di autorizzazioni OAuth2 con l'unione di ambiti esistenti e obbligatori. Non creare un duplicato né rimuovere scope non correlate.

  3. Registrare il id grant per la pulizia. Accedi come quell'utente quando esegui il client di test. Non forzare una nuova richiesta di consenso per la risorsa agente.

Configurare la convalida dei token

Creare il progetto API dell'agente se non ne è già disponibile uno:

dotnet new webapi --framework net10.0 --name AgentApi
cd AgentApi

Eseguire l'installazione Microsoft.Identity.Web dalla directory del progetto:

dotnet add package Microsoft.Identity.Web --version 4.17.0

Configurare l'API dell'agente in appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<tenant-id>",
    "ClientId": "<agent-client-id>"
  }
}

Sostituire il Program.cs del progetto con il codice seguente. Richiede l'ambito access_agent prima di restituire l'identità convalidata del chiamante:

using System.Security.Claims;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(
    builder.Configuration);
builder.Services.AddAuthorization();

var app = builder.Build();

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

app.MapGet("/whoami", (HttpContext context) =>
{
    context.VerifyUserHasAnyAcceptedScope("access_agent");

    ClaimsPrincipal user = context.User;
    string? objectId = user.GetObjectId();
    string? tenantId = user.GetTenantId();

    return Results.Ok(new { objectId, tenantId });
})
.RequireAuthorization();

app.Run();

AddMicrosoftIdentityWebApiAuthentication convalida la firma del token, l'autorità emittente, il destinatario e il periodo di validità. I criteri di autorizzazione possono quindi valutare ambiti, ruoli dell'app e altre attestazioni.

VerifyUserHasAnyAcceptedScope rifiuta un token valido che non contiene l'autorizzazione access_agent delegata.

Usare GetObjectId() e GetTenantId() per leggere l'identità stabile. Questi helper gestiscono sia i nomi di attestazione JWT originali che i nomi delle attestazioni mappati dal middleware di autenticazione.

Comprendere il percorso della richiesta

  1. Il client upstream autentica l'utente.
  2. Il client ottiene un token di accesso per access_agent.
  3. Il client invia Authorization: Bearer <token> all'API dell'agente.
  4. Il middleware di autenticazione ASP.NET Core convalida il token.
  5. L'API dell'agente applica i criteri di autorizzazione.

Eseguire il client di test

Avviare l'API dell'agente:

dotnet run --urls https://localhost:5001

In un altro terminale creare un progetto console all'esterno della directory API dell'agente:

dotnet new console --framework net10.0 --name AgentTestClient
cd AgentTestClient
dotnet add package Microsoft.Identity.Client

Sostituire il contenuto del progetto console Program.cs con questo codice. Sostituire l'ID tenant, l'ID client di test e l'ID client condiviso dell'agente:

using System.Net.Http.Headers;
using Microsoft.Identity.Client;

var client = PublicClientApplicationBuilder.Create("<upstream-client-id>")
    .WithAuthority("https://login.microsoftonline.com/<tenant-id>")
    .WithRedirectUri("http://localhost")
    .Build();

var result = await client
    .AcquireTokenInteractive(["api://<agent-client-id>/access_agent"])
    .ExecuteAsync();

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", result.AccessToken);
using var response = await http.GetAsync("https://localhost:5001/whoami");
Console.WriteLine($"HTTP {(int)response.StatusCode}");
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Eseguire dotnet run e accedere con l'utente indicato nell'autorizzazione del consenso. Prevedi HTTP 200 e l'ID oggetto e l'ID tenant dell'utente. Una richiesta a /whoami senza un token deve restituire 401. Non registrare il token o usare un token ID al suo posto.

Se l'API espone un altro ambito delegato e il client di test ha il consenso, richiedere anche un token per tale ambito da solo e chiamare /whoami. Verificare che il token abbia l'audience dell'API dell'agente, ma non contenga access_agent, e che la richiesta venga rifiutata. Questo test facoltativo con ambito negativo richiede un secondo ambito; l'installazione locale minima definisce solo access_agent. Un token per un'audience diversa verifica la convalida dell'audience, non l'autorizzazione dell'ambito.

Se l'accesso non riesce, controllare l'URI di reindirizzamento del client di test e la concessione per utente prima di modificare la configurazione dell'agente. Se HTTPS non funziona, correggere l'attendibilità del certificato di sviluppo anziché ignorare la convalida.

Pulire il test locale

Arrestare entrambi i progetti al termine. Mantenere la registrazione del client di test e dell'agente se si continua con l'attività successiva. Quando non è più necessaria una concessione di test, eliminarla con DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<grant-id> tramite il client di gestione, prima di eliminare la registrazione dell'app client. Non eliminare i client condivisi o i grant usati da altri utenti.

Passaggio successivo

Chiamare un'API personalizzata come utente connesso. Per limitare gli utenti che possono richiamare l'agente, vedere Controllare l'accesso utente agli agenti.