Chamar APIs personalizadas a partir de um agente usando .NET

Existem várias formas de chamar APIs personalizadas a partir de um agente. Dependendo do seu cenário, pode usar tanto IDownstreamApi, MicrosoftIdentityMessageHandler, como IAuthorizationHeaderProvider. Este guia explica as diferentes abordagens para chamar as suas próprias APIs protegidas de três formas.

Para chamar uma API a partir de um agente, é necessário obter um token de acesso que o agente possa usar para se autenticar à API. Recomendamos usar o Microsoft.Identity.Web SDK para .NET para chamar as suas APIs web. Este SDK simplifica o processo de aquisição e validação de tokens. Para outros idiomas, use o Microsoft Entra agent SDK para ID do agente.

Pré-requisitos

Uma identidade de agente com permissões apropriadas para chamar a API de destino. Precisas de um utilizador para o fluxo em nome dele.
A conta de utilizador de um agente com permissões apropriadas para chamar a API de destino.

Decida qual abordagem usar com base no seu cenário

A tabela seguinte ajuda-o a decidir qual a abordagem a usar. Para a maioria dos cenários, recomendamos usar IDownstreamApi.

Abordagem	Complexidade	Flexibilidade	Caso de uso
`IDownstreamApi`	Baixo	Medium	APIs REST padrão com configuração
`MicrosoftIdentityMessageHandler`	Medium	Alto	HttpClient com Injeção Direta (DI) e pipeline componível
`IAuthorizationHeaderProvider`	Alto	Muito alto	Controlo total sobre pedidos HTTP

IDownstreamApi é a forma preferida de chamar uma API protegida entre as três opções. É altamente configurável e requer alterações mínimas no código. Também oferece aquisição automática de tokens.

Use IDownstreamApi quando precisar dos seguintes itens listados:

Estás a chamar APIs REST padrão
Queres uma abordagem orientada pela configuração
Precisa de serialização e desserialização automáticas
Queres escrever código mínimo

MicrosoftIdentityMessageHandler do pacote Microsoft.Identity.Web.TokenAcquisition é um handler de delegação que adiciona autenticação aos pedidos HttpClient. Use isto quando precisar de funcionalidade completa do HttpClient com aquisição automática de tokens.

O pacote Microsoft.Identity.Web.TokenAcquisition já é referenciado por Microsoft.Identity.Web.AgentIdentities.

Use MicrosoftIdentityMessageHandler quando precisar dos seguintes itens listados:

Precisas de controlo detalhado sobre pedidos HTTP
Deseja compor múltiplos manipuladores de mensagens
Estás a integrar-te com código HttpClient já existente
Precisa de acesso ao HttpResponseMessage em bruto

IAuthorizationHeaderProvider de Microsoft.Identity.Web dá-lhe acesso direto aos cabeçalhos de autorização para controlo completo sobre pedidos HTTP. Isto significa que pode personalizar o processo de autenticação para se adequar às suas necessidades, incluindo adicionar ou modificar cabeçalhos conforme necessário. Este método também permite usar bibliotecas HTTP personalizadas para fazer chamadas de API.

Use IAuthorizationHeaderProvider quando precisar dos seguintes itens listados:

Precisas de controlo total sobre a construção dos pedidos HTTP
Estás a integrar com APIs HTTP não padrão
Precisas de usar o HttpClient sem DI
Estás a construir abstrações HTTP personalizadas

Chame a sua API

Depois de determinar o que funciona para si, proceda a ligar para a sua API web personalizada.

Advertência

Os segredos do cliente não devem ser usados como credenciais do cliente em ambientes de produção para modelos de identidade de agentes por motivos de segurança. Em vez disso, utilize métodos de autenticação mais seguros, como credenciais de identidade federada (FIC) com identidades geridas ou certificados de cliente. Estes métodos proporcionam maior segurança ao eliminar a necessidade de armazenar segredos sensíveis diretamente na configuração da sua aplicação.

Instale o pacote NuGet necessário:

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

Configure as opções de credencial do token e as suas APIs em 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 os seus serviços para adicionar suporte a API a jusante:

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

Chame a sua API protegida usando IDownstreamApi. Ao chamar a API, pode especificar a identidade do agente ou a identidade da conta de utilizador do agente usando os métodos WithAgentIdentity ou WithAgentUserIdentity. IDownstreamApi trata automaticamente da aquisição do token e anexa o token de acesso ao pedido.

Para WithAgentIdentity, ou chama a API usando um token exclusivo de aplicação (agente autónomo) ou em nome de um utilizador (agente interativo).

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, pode especificar um Nome Principal de Utilizador (UPN) ou uma Identidade de Objeto (OID) para identificar a conta de utilizador do 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's user account 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's user account 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 o pacote NuGet necessário:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Configure os seus serviços para adicionar autenticação com identidades de agentes e registe o Cliente Http com 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();

Adquira o token e chame a sua API protegida usando o HttpClient configurado. Pode especificar a identidade ou a conta de utilizador do agente usando os métodos WithAgentIdentity ou WithAgentUserIdentity.

Para WithAgentIdentity, ou chama a API usando um token exclusivo de aplicação (agente autónomo) ou em nome de um utilizador (agente interativo).

Para chamar a API usando um token apenas de aplicação para a identidade do agente, defina RequestAppToken para 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 chamar a API em nome de um utilizador para a identidade do agente, não defina RequestAppToken nem defina explicitamente para 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, pode especificar UPN ou OID para identificar a conta de utilizador do agente.

// Create request with agent's user account 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's user account 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 o pacote NuGet necessário:

dotnet add package Microsoft.Identity.Web.AgentIdentities

Configure os seus serviços para adicionar autenticação com identidades de agentes:

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

Configurar credenciais de autenticação no appsettings.json

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

Adquire e extrai o token de acesso e depois liga para a API web.

Para WithAgentIdentity, ou chama a API usando um token exclusivo de aplicação (agente autónomo) ou em nome de um utilizador (agente interativo).

Para o cenário apenas de token da app, use o método CreateAuthorizationHeaderForAppAsync.
Para o cenário do token OBO, use o método CreateAuthorizationHeaderForUserAsync

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, chama a API em nome de um utilizador usando o seu UPN ou 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);
    }
}

Comentários

Esta página foi útil?

Last updated on 2026-04-08

Chamar APIs personalizadas a partir de um agente usando .NET

Pré-requisitos

Decida qual abordagem usar com base no seu cenário

Chame a sua API

Conteúdo relacionado

Comentários

Recursos adicionais