驗證使用者至 ASP.NET Core 代理 API

上游客戶端會登入使用者,並將存取權杖傳送給您的代理 API。 本文設定 ASP.NET Core 代理程式 API 以驗證該權杖,並展示一個本地測試用戶端登入使用者並呼叫 /whoami。

驗證用來確認來電者的身份。 控制使用者對代理程式的存取 權會分別決定該身份是否能呼叫代理程式。

Prerequisites

  • 完成「 為您的代理建立身份」,包括租戶啟用與管理員交接。 記錄共用的用戶端 ID 以及代理程式身分識別的物件 ID。
  • .NET 10 SDK。 這些例子使用 Microsoft。Identity.Web 4.17.0。
  • 一個上游用戶端應用程式,可登入使用者並請求代理 API 的存取權杖,或註冊 本地測試用戶端的權限。
  • 在預覽同意步驟中,管理用戶端 已取得管理員對額外委派 Graph 權限 DelegatedPermissionGrant.ReadWrite.All 的同意。 請使用有權同意這些委派權限的管理員。 從授予全租戶管理員同意中選擇權限最低的支援角色,並與您的 Microsoft 代表確認任何額外的預覽同意需求。
  • 用於本地測試的受信任本地 HTTPS 開發憑證。 在您的開發機器上執行 dotnet dev-certs https --trust 並核准信任提示字句。 不要關閉憑證驗證。

註冊本地測試用戶端

如果您已有客戶端會讓使用者登入並呼叫您的代理程式,請跳過此節。 這個測試客戶端是一個獨立的普通應用程式註冊,而非另一個代理身份。

  1. 在代理程式的租戶中註冊一個名為 Agent API test client 的 單一租戶應用程式。
  2. 在 「驗證」 下,加入 行動與桌面應用程式 平台,並設定 redirect URI http://localhost。 不需要客戶端密鑰。
  3. 記錄其 應用程式(用戶端)ID。 在 企業應用程式下,找到對應的應用程式並記錄其 物件 ID。 令牌請求會使用用戶端 ID;同意授予會使用企業應用程式的物件 ID。

用戶端使用瀏覽器與 PKCE。 迴路重定向會在本地接收授權回應;API 呼叫仍然使用 HTTPS。

設定委派權限

上游用戶端需要委派權限,才能以代表已登入使用者呼叫代理程式 API。

  1. 在藍圖上 ,公開識別碼 URI 及委派範圍。 使用 access_agent 作為本導覽的範圍值。 保留現有範圍並設 api.requestedAccessTokenVersion 為 2。
  2. 在上游用戶端的 requiredResourceAccess. 中宣告該範圍。 使用共用代理程式用戶端 ID 作為 resourceAppId,並將暴露範圍的 GUID 與 "type": "Scope" 搭配使用。
  3. 依照下一節所述,授予測試使用者上游用戶端存取權限。 在預覽期間,瀏覽器同意流程不支援使用代理程式身分識別作為資源身分識別。

如需更多資訊,請參閱〈設定用戶端應用程式以存取 Web API〉以及〈在 Microsoft 身分識別平台 中的權限與同意〉。

依照該用戶端類型的驗證流程設定上游用戶端。 例如,請參閱 OAuth 2.0 授權代碼流程。 請求完整限定的代理程式 API 範圍:

api://<agent-client-id>/access_agent

在上游用戶端使用驗證函式庫。 不要向代理程式 API 傳送 ID 代幣或授權碼。

授予上游用戶端存取權限

請對這些 Microsoft Graph 要求使用管理用戶端,不要使用代理程式的執行階段認證資訊。 這項授權允許上游用戶端呼叫代理程式;但不會授予代理程式存取下游 API 的權限。

在執行請求之前,請先在 Microsoft Entra 系統管理中心 開啟管理應用程式的應用程式註冊。 在 API 權限下,選擇新增權限>Microsoft Graph>委派權限,新增該權限 DelegatedPermissionGrant.ReadWrite.All,並請授權管理員授予同意。 不要將這兩個管理權限用於佈建。 請勿將這些權限新增至代理程式或測試用戶端。

重新連線至三個已同意的權限範圍:

Disconnect-MgGraph
Connect-MgGraph -ClientId "<management-app-client-id>" `
    -TenantId "<tenant-id>" `
    -Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All", "DelegatedPermissionGrant.ReadWrite.All" `
    -ContextScope Process

如 設定管理用戶端 所示,使用 Invoke-MgGraphRequest。

  1. 檢查現有適用授權:

    GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq '<upstream-client-service-principal-object-id>' and resourceId eq '<agent-identity-object-id>'
    

    依照分頁操作。 適用於整個租戶的授權或測試使用者的授權可能已經包含 access_agent。

  2. 若無適用授權,請授予唯一將登入的使用者存取權限:

    POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
    Content-Type: application/json
    
    {
      "clientId": "<upstream-client-service-principal-object-id>",
      "resourceId": "<agent-identity-object-id>",
      "consentType": "Principal",
      "principalId": "<user-object-id>",
      "scope": "access_agent"
    }
    

    clientId 以及 resourceId 為服務主體 物件 ID,而非 OAuth 用戶端 ID。 如果該使用者已有授權但缺乏該範圍,請 將 OAuth2 權限授權範圍更新 為現有且必要範圍的聯合。 不要建立重複的範圍或移除無關的範圍。

  3. 記錄授權的 id ID 以便清理。 執行測試用戶端時,請以該使用者身分登入。 不要對代理資源強制顯示新的同意提示。

配置令牌驗證

如果您尚未建立代理 API 專案,請先建立:

dotnet new webapi --framework net10.0 --name AgentApi
cd AgentApi

從專案目錄安裝 Microsoft.Identity.Web :

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

在 appsettings.json 中設定代理程式 API:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<tenant-id>",
    "ClientId": "<agent-client-id>"
  }
}

請以以下程式碼替換專案的 Program.cs 。 它需要 access_agent 範圍,才會回傳呼叫者經過驗證的身分:

using System.Security.Claims;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(
    builder.Configuration);
builder.Services.AddAuthorization();

var app = builder.Build();

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

app.MapGet("/whoami", (HttpContext context) =>
{
    context.VerifyUserHasAnyAcceptedScope("access_agent");

    ClaimsPrincipal user = context.User;
    string? objectId = user.GetObjectId();
    string? tenantId = user.GetTenantId();

    return Results.Ok(new { objectId, tenantId });
})
.RequireAuthorization();

app.Run();

AddMicrosoftIdentityWebApiAuthentication 驗證令牌簽名、發行者、受眾及有效期限。 授權政策接著可以評估範圍、應用程式角色及其他聲明。

VerifyUserHasAnyAcceptedScope 拒絕未包含 access_agent 委派權限的有效權杖。

使用 GetObjectId() 和 GetTenantId() 來讀取穩定身份。 這些輔助程式同時處理原始 JWT 聲明名稱以及由驗證中介軟體對應的聲明名稱。

了解請求路徑

  1. 上游用戶端會讓使用者登入。
  2. 用戶端取得一個用於 access_agent 的存取權杖。
  3. 用戶端會將 Authorization: Bearer <token> 傳送給代理程式 API。
  4. ASP.NET Core 驗證中介軟體會驗證該權杖。
  5. 代理程式 API 會套用其授權政策。

執行測試用戶端

啟動代理程式 API:

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

在另一個終端機中,建立代理程式 API 目錄外的主控台專案:

dotnet new console --framework net10.0 --name AgentTestClient
cd AgentTestClient
dotnet add package Microsoft.Identity.Client

用這段程式碼替換主控台專案的 Program.cs 程式碼。 請將租戶 ID、測試用戶端的用戶端 ID 及代理程式共用用戶端 ID 替換:

using System.Net.Http.Headers;
using Microsoft.Identity.Client;

var client = PublicClientApplicationBuilder.Create("<upstream-client-id>")
    .WithAuthority("https://login.microsoftonline.com/<tenant-id>")
    .WithRedirectUri("http://localhost")
    .Build();

var result = await client
    .AcquireTokenInteractive(["api://<agent-client-id>/access_agent"])
    .ExecuteAsync();

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", result.AccessToken);
using var response = await http.GetAsync("https://localhost:5001/whoami");
Console.WriteLine($"HTTP {(int)response.StatusCode}");
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

以同意授權中指定的使用者身分執行 dotnet run 並登入。 預期 HTTP 200 以及該使用者的物件 ID 與租戶 ID。 對於未附帶權杖的 /whoami 請求,必須返回 401。 不要記錄該令牌,也不要用 ID 令牌代替。

如果你的 API 暴露了另一個委派範圍,且測試用戶端已同意該範圍,也請為該範圍請求一個令牌並呼叫 /whoami。 確認該令牌擁有代理 API 的受眾但缺少 access_agent,且請求被拒絕。 此可選的 scope 負向測試需要第二個範圍;最小的本地設定僅定義 access_agent。 不同受眾的令牌測試的是受眾驗證,而非範圍授權。

如果登入失敗,請先檢查測試用戶端的重新導向 URI 及每位使用者的授權,然後再變更代理程式的設定。 如果 HTTPS 失敗,請修正開發憑證的信任,而非繞過驗證。

清理本地測試

完成後就停止兩個專案。 若繼續進行下一個任務,請保留測試用戶端與代理程式註冊。 當你不再需要測試授權時,請在管理用戶端中使用 DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<grant-id> 刪除它,再刪除其用戶端應用程式的註冊。 不要刪除其他使用者使用的共用用戶端或授權。

下一步

以已登入使用者身分呼叫自訂 API。 若要限制哪些使用者可以呼叫代理程式,請參閱 「控制使用者對代理程式的存取」。