Llamar a APIs personalizadas desde un agente mediante .NET

Hay varias maneras de llamar a las API personalizadas desde un agente. En función de su escenario, puede usar IDownstreamApi, MicrosoftIdentityMessageHandlero IAuthorizationHeaderProvider. En esta guía se explican los distintos enfoques para llamar a sus propias API protegidas de las tres maneras.

Para llamar a una API desde un agente, debe obtener un token de acceso que el agente puede usar para autenticarse en la API. Se recomienda usar el SDK de Microsoft.Identity.Web para .NET para llamar a las API web. Este SDK simplifica el proceso de adquisición y validación de tokens. Para otros lenguajes, use el SDK del agente de Microsoft Entra para el identificador del agente.

Prerrequisitos

Una identidad del agente con los permisos adecuados para llamar a la API de destino. Necesita un usuario para el flujo de representación.
Un usuario del agente con los permisos adecuados para llamar a la API de destino.

Decidir qué enfoque usar en función de su escenario

La tabla siguiente le ayuda a decidir qué enfoque usar. Para la mayoría de los escenarios, se recomienda usar IDownstreamApi.

Enfoque	Complejidad	Flexibilidad	Caso de uso
`IDownstreamApi`	Low	Mediana	API REST estándar con configuración
`MicrosoftIdentityMessageHandler`	Mediana	High	HttpClient con inyección directa (DI) y canalización compuesta
`IAuthorizationHeaderProvider`	High	Muy alto	Control completo de las solicitudes HTTP

IDownstreamApi es la manera preferida de llamar a una API protegida entre las tres opciones. Es muy configurable y requiere cambios mínimos de código. También ofrece la adquisición automática de tokens.

Use IDownstreamApi cuando necesite los siguientes elementos enumerados:

Está llamando a las API REST estándar.
Quiere un enfoque basado en la configuración.
Necesita serialización y deserialización automáticas.
Quiere escribir código mínimo

MicrosoftIdentityMessageHandler del paquete Microsoft.Identity.Web.TokenAcquisition es un manejador delegante que agrega autenticación a las solicitudes de HttpClient. Úselo cuando necesite una funcionalidad completa de HttpClient con la adquisición automática de tokens.

Microsoft.Identity.Web.TokenAcquisition ya hace referencia al paquete Microsoft.Identity.Web.AgentIdentities.

Use MicrosoftIdentityMessageHandler cuando necesite los siguientes elementos enumerados:

Necesita un control específico sobre las solicitudes HTTP.
Quieres componer varios controladores de mensajes.
Estás integrando con código existente basado en HttpClient.
Necesita acceso a HttpResponseMessage bruto.

IAuthorizationHeaderProvider desde Microsoft.Identity.Web proporciona acceso directo a los encabezados de autorización para un control completo sobre las solicitudes HTTP. Esto significa que puede personalizar el proceso de autenticación para satisfacer sus necesidades, incluida la adición o modificación de encabezados según sea necesario. Este método también permite usar bibliotecas HTTP personalizadas para realizar llamadas API.

Use IAuthorizationHeaderProvider cuando necesite los siguientes elementos enumerados:

Necesita un control completo sobre la construcción de solicitudes HTTP.
Está integrando APIs HTTP no estándar
Necesita usar HttpClient sin DI
Va a crear abstracciones HTTP personalizadas.

Llamada a la API

Después de determinar qué funciona para ti, proceda con la llamada a la API web personalizada.

Advertencia

Los secretos de cliente no se deben usar como credenciales de cliente en entornos de producción para planos técnicos de identidad del agente debido a riesgos de seguridad. En su lugar, use métodos de autenticación más seguros, como credenciales de identidad federada (FIC) con identidades administradas o certificados de cliente. Estos métodos proporcionan seguridad mejorada eliminando la necesidad de almacenar secretos confidenciales directamente dentro de la configuración de la aplicación.

Instale el paquete NuGet necesario:

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

Configure las opciones de credenciales de token y las API en 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
    }
  }
}

Configure los servicios para agregar compatibilidad con la API de bajada:

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();

Llame a la API protegida mediante IDownstreamApi. Al llamar a la API, puede especificar la identidad del agente o la identidad de usuario del agente mediante los WithAgentIdentity métodos o WithAgentUserIdentity . IDownstreamApi controla automáticamente la adquisición de tokens y adjunta el token de acceso a la solicitud.

Para WithAgentIdentity, puede llamar a la API mediante un token de aplicación (agente autónomo) o en nombre de un usuario (agente interactivo).

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);
    }
}

Para WithAgentUserIdentity, puede especificar el nombre principal de usuario (UPN) o la identidad de objeto (OID) para identificar al usuario del 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);
    }

}

Instale el paquete NuGet necesario:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Configure los servicios para agregar autenticación con identidades de agente y registrar 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();

Adquiera el token y llame a la API protegida mediante el HttpClient configurado. Puede especificar la identidad del agente o el usuario del agente mediante los WithAgentIdentity métodos o WithAgentUserIdentity .

Para WithAgentIdentity, puede llamar a la API mediante un token de aplicación (agente autónomo) o en nombre de un usuario (agente interactivo).

Para llamar a la API usando un token de aplicación únicamente para la identidad del agente, establezca RequestAppToken en true.

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();
    }
}

Para llamar a la API en nombre de un usuario para la identidad del agente, no establezca RequestAppToken ni establezca explícitamente 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();
    }
}

Para usar WithAgentUserIdentity, puede especificar UPN o OID para identificar al usuario del 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();
}

Instale el paquete NuGet necesario:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Configure los servicios para agregar autenticación con identidades de 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();

Configuración de credenciales de autenticación en appsettings.json

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

Adquiera y extraiga el token de acceso y llame a la API web.

Para WithAgentIdentity, puede llamar a la API mediante un token de aplicación (agente autónomo) o en nombre de un usuario (agente interactivo).

Para el escenario de token solo de aplicación, use el método CreateAuthorizationHeaderForAppAsync.
Para el escenario de token de OBO, use el CreateAuthorizationHeaderForUserAsync método

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);
    }
}

Para WithAgentUserIdentity, llame a la API en nombre de un usuario mediante su 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);
    }
}

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-11-19

Compartir a través de

Llamar a APIs personalizadas desde un agente mediante .NET

Prerrequisitos

Decidir qué enfoque usar en función de su escenario

Llamada a la API

Contenido relacionado

Comentarios

Recursos adicionales