使用 .NET 从代理调用自定义 API

可通过多种方式从代理调用自定义 API。根据你的方案，可以使用IDownstreamApi、MicrosoftIdentityMessageHandler或IAuthorizationHeaderProvider中的任意一个。本指南解释了三种不同方法来调用您自己的受保护 API。

若要从代理调用 API，需要获取代理可用于向 API 进行身份验证的访问令牌。建议使用适用于 .NET 的 Microsoft.Identity.Web SDK 调用 Web API。此 SDK 简化了获取和验证令牌的过程。对于其他语言，请使用 Microsoft Entra ID 身份验证 SDK （sidecar）。

先决条件

具有调用目标 API 的适当权限的代理标识。你需要一个代表流的用户。
具有调用目标 API 的适当权限的代理用户帐户。

根据方案确定使用哪种方法

下表可帮助你确定使用哪种方法。对于大多数方案，我们建议使用 IDownstreamApi。

Approach	复杂性	灵活性	用例
`IDownstreamApi`	低	Medium	带有配置选项的标准 REST API
`MicrosoftIdentityMessageHandler`	Medium	高	具有直接注入（DI）和可组合管道的 HttpClient
`IAuthorizationHeaderProvider`	高	非常高	完全控制 HTTP 请求

IDownstreamApi 是三个选项中调用受保护 API 的首选方法。它高度可配置，需要最少的代码更改。它还提供自动令牌获取。

需要以下列出的项时使用 IDownstreamApi ：

正在调用标准 REST API
需要配置驱动的方法
需要自动序列化/反序列化
你想要编写最少的代码

MicrosoftIdentityMessageHandler 来自 Microsoft.Identity.Web.TokenAcquisition 包的委托处理程序，用于向 HttpClient 请求添加身份验证。当您需要具有自动令牌获取功能的完整 HttpClient 功能时，请使用此功能。

Microsoft.Identity.Web.TokenAcquisition 包已经被 Microsoft.Identity.Web.AgentIdentities 引用。

需要以下列出的项时使用 MicrosoftIdentityMessageHandler ：

需要对 HTTP 请求进行精细控制
你想要撰写多个消息处理程序
正在与基于 HttpClient 的现有程序代码集成
需要访问原始 HttpResponseMessage

IAuthorizationHeaderProvider 通过 Microsoft.Identity.Web ，你可以直接访问授权标头，以便完全控制 HTTP 请求。这意味着你可以自定义身份验证过程以满足你的需求，包括根据需要添加或修改标头。此方法还允许使用自定义 HTTP 库进行 API 调用。

需要以下列出的项时使用 IAuthorizationHeaderProvider ：

需要完全控制 HTTP 请求构造
你正在与非标准 HTTP API 进行集成
需要使用不使用 DI 的 HttpClient
正在构建自定义 HTTP 抽象

调用 API

确定适合自己的内容后，继续调用自定义 Web API。

Warning

由于安全风险，客户端机密不应在生产环境中用作代理标识蓝图的客户端凭据。而是使用更安全的身份验证方法，例如将联合标识凭据（FIC）与托管标识或客户端证书配合使用。这些方法通过消除直接在应用程序配置中存储敏感机密的需要，从而提供增强的安全性。

安装所需的 NuGet 包：

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

在 appsettings.json中配置令牌凭据选项和 API。

{
  "AzureAd": {
    "Instance": "https://login.partner.microsoftonline.cn/",
    "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
    }
  }
}

配置服务以添加下游 API 支持：

using Microsoft.AspNetCore.Authentication.OpenIdConnect;
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();

使用 IDownstreamApi.. 调用受保护的 API。调用 API 时，可以使用 WithAgentIdentity 方法或 WithAgentUserIdentity 方法指定代理标识或代理的用户帐户标识。 IDownstreamApi 自动处理令牌获取并将访问令牌附加到请求。

对于 WithAgentIdentity，您可以使用仅限应用程序的令牌（自治代理）或代表用户的令牌（交互式代理）来调用 API。

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

对于 WithAgentUserIdentity，可以指定用户主体名称（UPN）或对象标识（OID）来标识代理的用户帐户。

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

}

安装所需的 NuGet 包：

dotnet add package Microsoft.Identity.Web.AgentIdentities

将服务配置为使用代理标识添加身份验证，并将 HttpClient 注册到 MicrosoftIdentityMessageHandler：

using Microsoft.AspNetCore.Authentication.OpenIdConnect;
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();

使用配置的 HttpClient 获取令牌并调用受保护的 API。可以使用WithAgentIdentity或WithAgentUserIdentity方法指定代理标识或代理的用户帐户。

对于 WithAgentIdentity，您可以使用仅限应用程序的令牌（自治代理）或代表用户的令牌（交互式代理）来调用 API。

若要使用仅应用令牌调用代理标识的 API，请将 RequestAppToken 设置为 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
        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();
    }
}

若要代表用户为代理标识调用 API，请不要设置 RequestAppToken 或显式将其设置为 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
        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();
    }
}

若要使用 WithAgentUserIdentity，可以指定 UPN 或 OID 来标识代理的用户帐户。

// Create request with agent's user account identity authentication with UPN
public async Task<string> CallApiWithAgentUserIdentityByUpn(string agentIdentity, string userUpn)
{

    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> CallApiWithAgentUserIdentityByOid(string agentIdentity, string userOid)
{

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

安装所需的 NuGet 包：

dotnet add package Microsoft.Identity.Web.AgentIdentities

配置服务以使用代理标识添加身份验证：

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

在 appsettings.json 中配置身份验证凭据

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

获取和提取访问令牌，然后调用 Web API。

对于 WithAgentIdentity，您可以使用仅限应用程序的令牌（自治代理）或代表用户的令牌（交互式代理）来调用 API。

对于仅限应用的令牌方案，请使用 CreateAuthorizationHeaderForAppAsync 方法。
对于代表他方 (OBO) 令牌方案，请使用 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> GetUserData()
    {
        // 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);
    }
}

对于 WithAgentUserIdentity ，您可以使用用户的 UPN 或 OID 代表他们调用 API。

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

Last updated on 2026-09-03

使用 .NET 从代理调用自定义 API

先决条件

根据方案确定使用哪种方法

调用 API

相关内容

其他资源