使用 .NET 從代理呼叫自訂 API

有多種方式可以從代理呼叫自訂 API。根據你的情境，你可以使用 IDownstreamApi、 MicrosoftIdentityMessageHandler或 IAuthorizationHeaderProvider。本指南說明了呼叫你自己受保護 API 的不同方法，涵蓋三種方式。

要從代理呼叫 API，你需要取得一個存取權杖，代理可以用來驗證自己對 API 的身份。我們建議使用 Microsoft。Identity.Web SDK 用於.NET呼叫你的網頁 API。此 SDK 簡化了取得與驗證憑證的流程。其他語言則使用 Microsoft Entra ID Auth SDK（sidecar）。

先決條件

一個具有適當權限以呼叫目標 API 的代理身份。你需要一個代表流程的使用者。
代理人的使用者帳號，並擁有適當權限來呼叫目標 API。

根據你的情況決定要採用哪種方法

以下表格將協助你決定採用哪種方法。在大多數情況下，我們建議使用 IDownstreamApi。

方法	複雜性	靈活性	用例
`IDownstreamApi`	低	中等	標準 REST API 與設定
`MicrosoftIdentityMessageHandler`	中等	高	具備直接注入（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

確定適合你的方法後，接著呼叫你自訂的網頁 API。

警告

由於安全風險，客戶端秘密不應在生產環境中作為代理身份藍圖的客戶端憑證使用。相反地，應使用更安全的認證方法，例如聯邦身份憑證（FIC）搭配管理身份或用戶端憑證。這些方法透過消除直接在應用程式配置中儲存敏感秘密的需求，提升安全性。

安裝所需的 NuGet 套件：

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

appsettings.json內的 Token 認證選項以及您的 API 進行配置。

{
  "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
    }
  }
}

配置您的服務以增加下游 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 or 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 OR 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.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-blueprint-id",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

取得並擷取存取權杖，然後呼叫網路 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);
    }
}

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-08-16

使用 .NET 從代理呼叫自訂 API

先決條件

根據你的情況決定要採用哪種方法

調用您的 API

相關內容

意見反應

其他資源