以代理程式呼叫自訂 API 搭配 ASP.NET Core

當您的雲端代理程式呼叫具有自身權限的自訂 API 時,請使用僅限應用程式存取權,而非已登入使用者的存取權限。 在本導覽中,授權使用者會觸發代理程式,並觸發 Microsoft。Identity.Web 會獲得一個僅限應用程式的令牌用於下游呼叫。

您將設定認證、授權存取並驗證受保護的 API 回應。 使用者呼叫代理程式的權限與代理程式呼叫下游 API 的權限是不同的檢查項目。

先決條件

  • 一個現有的 ASP.NET Core 網頁 API 專案,以及其目標框架的 .NET SDK。 這些範例已在 .NET 10 和 Microsoft 上進行測試。Identity.Web 4.17.0;這些是測試版本,而非最低支援版本。
  • 完成 「為您的代理程式建立身分識別」,包括租用戶啟用、系統管理員核准,以及已記錄的用戶端 ID 和物件 ID。
  • 在藍圖上註冊的認證憑證:用於本地測試的憑證,或 Azure 主機的託管身份聯邦認證憑證。
  • 一個自訂 API,揭露應用程式權限(應用程式角色),以及其應用程式 ID URI 和 HTTPS 端點。 API 必須驗證存取權杖並強制執行該角色。
  • 管理員授予 下游應用程式權限。 若要取得標準的租戶範圍同意自訂 API,雲端 應用程式管理員、 應用程式管理員或 AI 管理員 可以授予同意。 Microsoft Graph 應用程式權限則需要 特權角色管理員。 請與您的 Microsoft 代表確認此預覽版適用的角色。 請參閱授與全租用戶管理員同意。
  • 具有Application.Read.All可驗證指派的已授權 Microsoft Graph 管理用戶端。 若要進行委派存取,已登入的使用者還需要支援的角色,例如 Directory Readers。 此讀取權限不會授予執行時存取權限。
  • 透過 驗證使用者至代理 API,並透過 Agent.User 控制設定、驗證並指派代理 存取權的呼叫者。 完成該流程中的兩個角色定義步驟。 樣本會 RequireRole("Agent.User")保留;下游同意不授權來電者。

安裝套件

如果您沒有現有專案,請用 dotnet new webapi --framework net10.0 --name AgentApi 建立一個專案,然後執行 cd AgentApi。 在將此指引加入現有專案時,請保留您現有的目標框架。

從包含您網頁 API 專案檔案的目錄執行以下指令:

dotnet add package Microsoft.Identity.Web --version 4.17.0

設定藍圖憑證

請使用 API 執行環境的設定。 設定一個憑證來源,而非兩個。

設定本機開發憑證

在代理程式專案的 appsettings.json 中,將 AzureAd:Instance 設為 https://login.microsoftonline.com/、將 AzureAd:TenantId 設為您的租戶 ID,並將 AzureAd:ClientId 設為設定期間記錄的用戶端 ID。

請使用 安裝時註冊的憑證。 你需要包含私鑰的對應 PFX,而非僅上傳到 Microsoft Graph 的公開憑證。

在 appsettings.Development.json中,請使用此 ClientCredentials 陣列。 不要附加管理身分識別認證,也不要將 PFX 檔案提交到版本控制。

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "<absolute-path-to-local-pfx>"
      }
    ]
  }
}

在啟動應用程式的 PowerShell 終端機中,設定 $env:ASPNETCORE_ENVIRONMENT = "Development" 並設定 $env:AzureAd__ClientCredentials__0__CertificatePassword = Read-Host "PFX password" -MaskInput。 使用 PowerShell 7 來 -MaskInput。 環境變數提供密碼,但不會將其放入 JSON 檔案或 shell 歷史中。 停止應用程式後,再用 Remove-Item Env:\AzureAd__ClientCredentials__0__CertificatePassword 清除。 不要在正式環境中使用這種本機檔案設定。

警告

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

授與應用程式權限

依照建立程序所述,在藍圖中 requiredResourceAccess宣告 API 的應用程式角色。 宣告某項權限並不會授予該權限。

在同意請求與權杖請求中,使用自訂 API 已設定的應用程式 ID URI /.default 。 預設的 URI 格式為 api://<custom-api-client-id>,但若 API 定義了自訂 URI,則必須改用。

  1. 請管理員在瀏覽器中開啟以下網址,登入並檢視所要求的權限。 替換佔位符,將查詢參數值以 URL 編碼,並將這些行合併成一個 URL。 使用在藍圖中註冊的 web 重新導向 URI,即使代理程式僅在無人值守時執行。 產生一個唯一的 state 值並保留它以驗證回調。

    GET https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent
        ?client_id=<agent-client-id>
        &scope=<custom-api-application-id-uri>/.default
        &redirect_uri=<registered-web-redirect-uri>
        &state=<state>
    
  2. 將回傳的 state 與您傳送的值進行比對。 確認 admin_consent=True 此參數存在,且未回傳任何 error 參數。 錯誤回撥還包括 admin_consent=True。 檢查預期租戶,但不要使用回呼中的租戶值來驗證或授權來電者。 關於回應格式,請參閱 Microsoft 身分識別平台 的管理員同意。

  3. 開啟 Microsoft Graph Explorer,並以授權管理帳戶登入同一租戶。 使用 修改權限 請求 Application.Read.All,並在需要時由授權管理員授與同意。 選擇 GET 並選擇 v1.0,然後執行以下請求。 Graph Explorer 提供其管理存取權牌;不要使用代理的下游代幣。

    GET https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-object-id>/appRoleAssignments
    

    請使用建立時所記錄的代理程式身分 id 進行 <agent-identity-object-id>,而不是其共用的 OAuth 用戶端 ID 或藍圖的物件 ID。 遵循任何 @odata.nextLink 值。 確認 principalId 是代理程式身分的物件 ID,resourceId 是自訂 API 的服務主體物件 ID,且 appRoleId 是預期角色。 關於所需的讀取權限與委派使用者角色,請參閱 「列出 appRoleAssignments」。

請預留時間讓新的指派顯現。 如果仍未顯示,請先確認已核准的權限與租戶,然後再申請代幣。

設定 ASP.NET Core

在 Program.cs中,註冊 Microsoft.Identity.Web、HTTP 用戶端,以及入站 AgentUser 授權政策。 此路徑使用一般機密客戶端令牌取得,且不包含 AddAgentIdentities 或 WithAgentIdentity。 來電呼叫者的令牌是代理 API 的;下游應用程式專用的代幣則用於自訂 API。

using System.Net.Http.Headers;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

builder.Services.AddHttpClient();
builder.Services.AddAuthorization(options =>
{
    options.AddPolicy(
        "AgentUser",
        policy => policy.RequireRole("Agent.User"));
});

var app = builder.Build();

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

// Map the custom API endpoint before app.Run().
app.Run();

呼叫 API

請使用 IAuthorizationHeaderProvider.CreateAuthorizationHeaderForAppAsync。 將自訂 API 的 .default scope 以字串傳遞。 用你用來取得同意的同一個 URI 取代 <custom-api-application-id-uri> ,然後用 API 端點替換 https://api.contoso.com/data 。 提供者會直接使用已設定的用戶端 ID 與認證。

在 Program.cs 中的註解處插入以下端點,並置於 app.Run() 之前。 所需的 using 指令已經在檔案的最上方了。 端點會取得僅應用程式的授權標頭,並將其傳送至自訂 API:

app.MapGet("/custom-api", async (
    IAuthorizationHeaderProvider authorizationHeaderProvider,
    IHttpClientFactory httpClientFactory) =>
{
    string authorizationHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForAppAsync(
            "<custom-api-application-id-uri>/.default");

    HttpClient client = httpClientFactory.CreateClient();
    client.DefaultRequestHeaders.Authorization =
        AuthenticationHeaderValue.Parse(authorizationHeader);

    using HttpResponseMessage response =
        await client.GetAsync("https://api.contoso.com/data");
    response.EnsureSuccessStatusCode();

    return Results.Content(
        await response.Content.ReadAsStringAsync(),
        response.Content.Headers.ContentType?.ToString());
})
.RequireAuthorization("AgentUser");

回傳的授權標頭包含 Bearer 配置。 不要從生產端點回傳代幣或授權標頭。

範例需要一個已驗證且擁有該 Agent.User 角色的呼叫者。 在允許呼叫者觸發僅應用程式操作之前,請透過 代理程式的入站存取原則 設定該指派。

僅請求端點所需的應用程式權限。 有關定義及授予應用程式角色的指引,請參閱應用程式角色。

驗證 API 存取權

成功的令牌回應並不代表已獲得 API 授權。

  1. 在已設定藍圖憑證可用的環境中,從專案目錄執行專案。 受管理身份設定需要一台已設定指定管理身份與聯邦的 Azure 主機;但不提供本機工作站憑證。

    dotnet run --urls https://localhost:5001
    

    對於工作站,請先完成 「設定本機開發憑證」。 如有需要dotnet dev-certs https --trust,請信任 ASP.NET Core 開發憑證;這可能需要互動式確認。 不要停用憑證驗證。 若僅針對未驗證的 401 回應進行無人值守的本地煙霧測試,您可以改為使用 dotnet run --urls http://localhost:5001,並在不帶權杖的情況下呼叫該 HTTP URL。 不要透過 HTTP 傳送存取權杖。

  2. 使用從 將使用者驗證至代理程式 API 的上游客戶端,取得代理程式 API 的存取權杖,並具備所需的委派範圍與 Agent.User 角色。 變更指派後申請新的令牌。 在測試 shell 中將其設為 AGENT_API_ACCESS_TOKEN 環境變數,且不將其記錄在原始碼控制或 shell 歷史中。 不要替換 ID 權杖、Graph 管理權杖或下游自訂 API 權杖。

  3. 在獨立的 PowerShell 終端機中,呼叫代理端點:

    $response = Invoke-WebRequest `
        -Uri "https://localhost:5001/custom-api" `
        -Headers @{ Authorization = "Bearer $env:AGENT_API_ACCESS_TOKEN" }
    $response.StatusCode
    $response.Content
    

    對於回傳 200 OK 的 API 端點,預期會有 200 及其回應主體。 代理程式是以自身身份呼叫自訂 API,而非以入站使用者身份呼叫。 下游未成功狀態會導致 EnsureSuccessStatusCode 失敗;此範例不會將下游錯誤轉換為對應的入站狀態碼。

  4. 重複請求且不使用授權標頭:來自代理程式的 expect 401 Unauthorized 。 如果一個本來有效的代理 API 令牌缺少 Agent.User,而且該令牌是由租戶簽發,則預期會出現 403 Forbidden。 當需要指派時,租用戶可能會先拒絕權杖簽發。

  5. 在下游 API 中,確認簽章、發行者、受眾、存續時間及所需應用程式角色。 請將 oid 已驗證的代幣與代理身份物件 ID(而非藍圖物件 ID)進行比較,並檢查其 roles 聲明。 請參閱「 在下游 API 中驗證代理程式 ID 令牌」。 單憑成功的代幣回應,並不能證明這些檢查。

  6. 測試下游 API 拒絕缺少其所需角色的令牌,使用獨立的測試身份或固定裝置,而非移除生產授權。 預期在該 API 會遭到拒絕;不要從代理的例外回應推斷其狀態。

不要記錄存取權杖、憑證斷言或私鑰。 在排除故障時記錄相關 ID 與請求時間。

下一步

驗證下游 API 中的代理程式 ID 代幣