Chiamare API personalizzate da un agente tramite .NET

Esistono diversi modi per chiamare API personalizzate da un agente. A seconda dello scenario, è possibile usare IDownstreamApi, MicrosoftIdentityMessageHandlero IAuthorizationHeaderProvider. Questa guida illustra i diversi approcci per chiamare le proprie API protette in tutti e tre i modi.

Per chiamare un'API da un agente, è necessario ottenere un token di accesso che l'agente può usare per autenticarsi all'API. È consigliabile usare Microsoft.Identity.Web SDK per .NET per chiamare le API Web. Questo SDK semplifica il processo di acquisizione e convalida dei token. Per altre lingue, usare Microsoft Entra agent SDK per l'ID agente.

Prerequisiti

Identità dell'agente con autorizzazioni appropriate per chiamare l'API di destinazione. È necessario un utente per il flusso on-behalf-of.
Un utente agente con autorizzazioni appropriate per chiamare l'API di destinazione.

Decidere quale approccio usare in base allo scenario

La tabella seguente consente di decidere quale approccio usare. Per la maggior parte degli scenari, è consigliabile usare IDownstreamApi.

Avvicinarsi	Complessità	Flessibilità	Caso d'uso
`IDownstreamApi`	Low	Intermedio	API REST standard con configurazione
`MicrosoftIdentityMessageHandler`	Intermedio	High	HttpClient con inserimento diretto (DI) e pipeline componibile
`IAuthorizationHeaderProvider`	High	Molto alto	Controllo completo sulle richieste HTTP

IDownstreamApi è il modo preferito per chiamare un'API protetta tra le tre opzioni. È altamente configurabile e richiede modifiche minime al codice. Offre anche l'acquisizione automatica dei token.

Usare IDownstreamApi quando sono necessari gli elementi elencati di seguito:

Si chiamano API REST standard
Si vuole un approccio basato sulla configurazione
È necessaria la serializzazione/deserializzazione automatica
Si vuole scrivere codice minimo

MicrosoftIdentityMessageHandler dal pacchetto Microsoft.Identity.Web.TokenAcquisition è un gestore di delega che aggiunge l'autenticazione alle richieste HttpClient. Usare questa opzione quando è necessaria una funzionalità HttpClient completa con l'acquisizione automatica dei token.

Il pacchetto Microsoft.Identity.Web.TokenAcquisition è già a cui fa riferimento Microsoft.Identity.Web.AgentIdentities.

Usare MicrosoftIdentityMessageHandler quando sono necessari gli elementi elencati di seguito:

È necessario un controllo granulare sulle richieste HTTP
Si desidera comporre più gestori di messaggi
Stai integrando con il codice esistente basato su HttpClient
È necessario accedere a HttpResponseMessage non elaborato

IAuthorizationHeaderProvider da Microsoft.Identity.Web consente di accedere direttamente alle intestazioni di autorizzazione per il controllo completo sulle richieste HTTP. Ciò significa che è possibile personalizzare il processo di autenticazione in base alle proprie esigenze, inclusa l'aggiunta o la modifica di intestazioni in base alle esigenze. Questo metodo consente anche di usare librerie HTTP personalizzate per effettuare chiamate API.

Usare IAuthorizationHeaderProvider quando sono necessari gli elementi elencati di seguito:

È necessario il controllo completo sulla costruzione di richieste HTTP
Ti stai integrando con gli API HTTP non standard.
È necessario usare HttpClient senza DI
Si stanno creando astrazioni HTTP personalizzate

Chiama la tua API

Dopo aver determinato cosa funziona per te, procedi con la chiamata alla tua API Web personalizzata.

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.

Installare il pacchetto NuGet necessario:

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

Configurare le opzioni delle credenziali dei token e le API in appsettings.json.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-blueprint-id",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  },
  "DownstreamApis": {
    "MyApi": {
      "BaseUrl": "https://api.example.com",
      "Scopes": ["api://my-api-client-id/read", "api://my-api-client-id/write"],
      "RelativePath": "/api/v1",
      "RequestAppToken": false
    }
  }
}

Configurare i servizi per aggiungere il supporto dell'API downstream:

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Register downstream APIs
builder.Services.AddDownstreamApis(
    builder.Configuration.GetSection("DownstreamApis"));

// Add Agent Identities support
builder.Services.AddAgentIdentities();

builder.Services.AddControllersWithViews();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

Chiamare l'API protetta usando IDownstreamApi. Quando si chiama l'API, è possibile specificare l'identità dell'agente o l'identità utente dell'agente usando i WithAgentIdentity metodi o WithAgentUserIdentity . IDownstreamApi gestisce automaticamente l'acquisizione del token e collega il token di accesso alla richiesta.

Per WithAgentIdentity, è possibile chiamare l'API usando un token solo per app (agente autonomo) o per conto di un utente (agente interattivo).

using Microsoft.Identity.Abstractions;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize]
public class ProductsController : Controller
{
    private readonly IDownstreamApi _api;

    public ProductsController(IDownstreamApi api)
    {
        _api = api;
    }

    // GET request for app only token scenario for agent identity
    public async Task<IActionResult> Index()
    {

        string agentIdentity = "<your-agent-identity>";
        var products = await _api.GetForAppAsync<List<Product>>(
            "MyApi",
            "products",
            options => options.WithAgentIdentity(agentIdentity));

        return View(products);
    }

    // GET request for on-behalf of user token scenario for agent identity
    public async Task<IActionResult> UserProducts()
    {

        string agentIdentity = "<your-agent-identity>";
        var products = await _api.GetForUserAsync<List<Product>>(
            "MyApi",
            "products",
            options => options.WithAgentIdentity(agentIdentity));

        return View(products);
    }
}

Per WithAgentUserIdentity, è possibile specificare il User Principal Name (UPN) o l'Object Identity (OID) per identificare l'utente agente.

using Microsoft.Identity.Abstractions;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize]
public class ProductsController : Controller
{
    private readonly IDownstreamApi _api;

    public ProductsController(IDownstreamApi api)
    {
        _api = api;
    }

    // GET request for agent user identity using UPN
    public async Task<IActionResult> Index()
    {

        string agentIdentity = "<your-agent-identity>";
        string userUpn = "user@contoso.com";

        var products = await _api.GetForUserAsync<List<Product>>(
            "MyApi",
            "products",
            options => options.WithAgentUserIdentity(agentIdentity, userUpn));
        return View(products);
    }

    // GET request for agent user identity using OID
    public async Task<IActionResult> UserProducts()
    {

        string agentIdentity = "<your-agent-identity>";
        string userOid = "user-object-id";

        var products = await _api.GetForUserAsync<List<Product>>(
            "MyApi",
            "products",
            options => options.WithAgentUserIdentity(agentIdentity, userOid));

        return View(products);
    }

}

Installare il pacchetto NuGet necessario:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Configurare i servizi per aggiungere l'autenticazione con le identità dell'agente e registrare HttpClient con MicrosoftIdentityMessageHandler:

using Microsoft.Identity.Web;
using Microsoft.Identity.Abstractions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

// Configure named HttpClient with authentication
builder.Services.AddHttpClient("MyApiClient", client =>
{
    client.BaseAddress = new Uri("https://api.example.com");
    client.DefaultRequestHeaders.Add("Accept", "application/json");
    client.Timeout = TimeSpan.FromSeconds(30);
})
.AddHttpMessageHandler(sp =>
{
    var authProvider = sp.GetRequiredService<IAuthorizationHeaderProvider>();
    return new MicrosoftIdentityMessageHandler(
        authProvider,
        new MicrosoftIdentityMessageHandlerOptions
        {
            Scopes = new[] { "api://my-api-client-id/read" },
        });
});

builder.Services.AddControllersWithViews();

// Add Agent Identities support
builder.Services.AddAgentIdentities();


var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

Acquisire il token e chiamare l'API protetta utilizzando l'HttpClient configurato. È possibile specificare l'identità dell'agente o l'utente dell'agente usando i WithAgentIdentity metodi o WithAgentUserIdentity .

Per WithAgentIdentity, è possibile chiamare l'API usando un token solo applicazione (agente autonomo) o per conto di un utente (agente interattivo).

Per impostare RequestAppToken su true per chiamare l'API usando un token dell'app soltanto per l'identità dell'agente.

public class MyService
{
    private readonly HttpClient _httpClient;

    public MyService(IHttpClientFactory httpClientFactory)
    {
        _httpClient = httpClientFactory.CreateClient("MyApiClient");
    }

    public async Task<string> CallApiWithAgentIdentity(string agentIdentity)
    {
        // Create request with agent identity authentication
        string agentIdentity = "<your-agent-identity>";
        var request = new HttpRequestMessage(HttpMethod.Get, "/api/data")
            .WithAuthenticationOptions(options => 
            {
                options.WithAgentIdentity(agentIdentity);
                options.RequestAppToken = true;
            });

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

Per chiamare l'API per conto di un utente per l'identità dell'agente, non impostarla RequestAppToken o impostarla in modo esplicito su false.

public class MyService
{
    private readonly HttpClient _httpClient;

    public MyService(IHttpClientFactory httpClientFactory)
    {
        _httpClient = httpClientFactory.CreateClient("MyApiClient");
    }

    public async Task<string> CallApiWithAgentIdentity(string agentIdentity)
    {
        // Create request with agent identity authentication
        string agentIdentity = "<your-agent-identity>";
        var request = new HttpRequestMessage(HttpMethod.Get, "/api/data")
            .WithAuthenticationOptions(options =>
            {
                options.WithAgentIdentity(agentIdentity);
                options.RequestAppToken = false;
            });

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

Per usare WithAgentUserIdentity, è possibile specificare UPN o OID per identificare l'utente dell'agente.

// Create request with agent user identity authentication with UPN
public async Task<string> CallApiWithAgentUserIdentity(string agentIdentity, string userUpn)
{
    string agentIdentity = "<your-agent-identity>";
    string userUpn = "<your-user-upn>";

    var request = new HttpRequestMessage(HttpMethod.Get, "/api/userdata")
        .WithAuthenticationOptions(options => 
        {
            options.WithAgentUserIdentity(agentIdentity, userUpn);
            options.Scopes.Add("https://myapi.domain.com/user.read");
        });

    var response = await _httpClient.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadAsStringAsync();
}

// Create request with agent user identity authentication with OID
public async Task<string> CallApiWithAgentUserIdentity(string agentIdentity, string userUpn)
{
    string agentIdentity = "<your-agent-identity>";
    string userOid = "<your-user-oid>";

    var request = new HttpRequestMessage(HttpMethod.Get, "/api/userdata")
        .WithAuthenticationOptions(options => 
        {
            options.WithAgentUserIdentity(agentIdentity, userOid);
            options.Scopes.Add("https://myapi.domain.com/user.read");
        });

    var response = await _httpClient.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadAsStringAsync();
}

Installare il pacchetto NuGet necessario:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Configurare i servizi per aggiungere l'autenticazione con le identità dell'agente:

using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// With Microsoft.Identity.Web
builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi();

builder.Services.AddAgentIdentities();

var app = builder.Build();

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

app.Run();

Configurare le credenziali di autenticazione in appsettings.json

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-blueprint-id",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Acquisire ed estrarre il token di accesso e quindi chiamare l'API Web.

Per WithAgentIdentity, puoi chiamare l'API usando un token solo per app (agente autonomo) oppure per conto di un utente (agente interattivo).

Per lo scenario token solo per app, usare il metodo CreateAuthorizationHeaderForAppAsync.
Per lo scenario del token OBO, usare il CreateAuthorizationHeaderForUserAsync metodo

using Microsoft.Identity.Abstractions;

[Authorize]
public class CustomApiController : Controller
{
    private readonly IAuthorizationHeaderProvider _headerProvider;

    public CustomApiController(
        IAuthorizationHeaderProvider headerProvider,
    {
        _headerProvider = headerProvider;
    }

    // App only token scenario for agent identity
    public async Task<IActionResult> GetBackgroundData()
    {
        // Configure options for the agent identity
        string agentIdentity = "agent-identity-guid";
        var options = new AuthorizationHeaderProviderOptions()
            .WithAgentIdentity(agentIdentity);

        // Acquire an access token for the agent identity
        var authHeader = await _headerProvider.CreateAuthorizationHeaderForAppAsync(
            scopes: new[] { "api://my-api/.default" }, options: options);

        // Call the protected API
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", authHeader);

        var response = await client.GetAsync("https://api.example.com/background");
        var data = await response.Content.ReadFromJsonAsync<BackgroundData>();

        return Ok(data);
    }

    // On-behalf of user token scenario for agent identity
    public async Task<IActionResult> GetBackgroundData()
    {
        // Configure options for the agent identity
        string agentIdentity = "agent-identity-guid";
        var options = new AuthorizationHeaderProviderOptions()
            .WithAgentIdentity(agentIdentity);

        // Acquire an access token for the agent identity
        var authHeader = await _headerProvider.CreateAuthorizationHeaderForUserAsync(
            scopes: new[] { "api://my-api/.default" }, options: options);

        // Call the protected API
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", authHeader);

        var response = await client.GetAsync("https://api.example.com/background");
        var data = await response.Content.ReadFromJsonAsync<BackgroundData>();

        return Ok(data);
    }
}

Per WithAgentUserIdentity, chiami l'API per conto di un utente usando il loro UPN o OID.

using Microsoft.Identity.Abstractions;

[Authorize]
public class CustomApiController : Controller
{
    private readonly IAuthorizationHeaderProvider _headerProvider;

    public CustomApiController(IAuthorizationHeaderProvider headerProvider)
    {
        _headerProvider = headerProvider;
    }

    // App only token scenario for agent identity
    public async Task<IActionResult> GetBackgroundData()
    {
        // Configure options for the agent identity
        string agentIdentity = "agent-identity-guid";
        string userUpn = "user@contoso.com";

        var options = new AuthorizationHeaderProviderOptions()
            .WithAgentUserIdentity(agentIdentity, userUpn);

        // Create a ClaimsPrincipal to enable token caching
        ClaimsPrincipal user = new ClaimsPrincipal();

        // Acquire an access token for the agent identity
        var authHeader = await _headerProvider.CreateAuthorizationHeaderForAppAsync(
            scopes: new[] { "api://my-api/.default" }, options: options, user: user);

        // Call the protected API
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", authHeader);

        var response = await client.GetAsync("https://api.example.com/background");
        var data = await response.Content.ReadFromJsonAsync<BackgroundData>();

        return Ok(data);
    }

    // On-behalf of user token scenario for agent identity
    public async Task<IActionResult> GetBackgroundData()
    {
        // Configure options for the agent identity
        string agentIdentity = "agent-identity-guid";
        string userUpn = "user@contoso.com";

        var options = new AuthorizationHeaderProviderOptions()
            .WithAgentUserIdentity(agentIdentity, userUpn);

        // Create a ClaimsPrincipal to enable token caching
        ClaimsPrincipal user = new ClaimsPrincipal();

        // Acquire an access token for the agent identity
        var authHeader = await _headerProvider.CreateAuthorizationHeaderForAppAsync(
            scopes: new[] { "api://my-api/.default" }, options: options, user: user);

        // Call the protected API
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", authHeader);

        var response = await client.GetAsync("https://api.example.com/background");
        var data = await response.Content.ReadFromJsonAsync<BackgroundData>();

        return Ok(data);
    }
}

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-19

Condividi tramite

Chiamare API personalizzate da un agente tramite .NET

Prerequisiti

Decidere quale approccio usare in base allo scenario

Chiama la tua API

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive