上游客戶端會登入使用者,並將存取權杖傳送給您的代理 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並核准信任提示字句。 不要關閉憑證驗證。
註冊本地測試用戶端
如果您已有客戶端會讓使用者登入並呼叫您的代理程式,請跳過此節。 這個測試客戶端是一個獨立的普通應用程式註冊,而非另一個代理身份。
- 在代理程式的租戶中註冊一個名為 Agent API test client 的 單一租戶應用程式。
- 在 「驗證」 下,加入 行動與桌面應用程式 平台,並設定 redirect URI
http://localhost。 不需要客戶端密鑰。 - 記錄其 應用程式(用戶端)ID。 在 企業應用程式下,找到對應的應用程式並記錄其 物件 ID。 令牌請求會使用用戶端 ID;同意授予會使用企業應用程式的物件 ID。
用戶端使用瀏覽器與 PKCE。 迴路重定向會在本地接收授權回應;API 呼叫仍然使用 HTTPS。
設定委派權限
上游用戶端需要委派權限,才能以代表已登入使用者呼叫代理程式 API。
- 在藍圖上 ,公開識別碼 URI 及委派範圍。 使用
access_agent作為本導覽的範圍值。 保留現有範圍並設api.requestedAccessTokenVersion為2。 - 在上游用戶端的
requiredResourceAccess. 中宣告該範圍。 使用共用代理程式用戶端 ID 作為resourceAppId,並將暴露範圍的 GUID 與"type": "Scope"搭配使用。 - 依照下一節所述,授予測試使用者上游用戶端存取權限。 在預覽期間,瀏覽器同意流程不支援使用代理程式身分識別作為資源身分識別。
如需更多資訊,請參閱〈設定用戶端應用程式以存取 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。
檢查現有適用授權:
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。若無適用授權,請授予唯一將登入的使用者存取權限:
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 權限授權範圍更新 為現有且必要範圍的聯合。 不要建立重複的範圍或移除無關的範圍。記錄授權的
idID 以便清理。 執行測試用戶端時,請以該使用者身分登入。 不要對代理資源強制顯示新的同意提示。
配置令牌驗證
如果您尚未建立代理 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 聲明名稱以及由驗證中介軟體對應的聲明名稱。
了解請求路徑
- 上游用戶端會讓使用者登入。
- 用戶端取得一個用於
access_agent的存取權杖。 - 用戶端會將
Authorization: Bearer <token>傳送給代理程式 API。 - ASP.NET Core 驗證中介軟體會驗證該權杖。
- 代理程式 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。 若要限制哪些使用者可以呼叫代理程式,請參閱 「控制使用者對代理程式的存取」。