當您的雲端代理程式呼叫具有自身權限的自訂 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,則必須改用。
請管理員在瀏覽器中開啟以下網址,登入並檢視所要求的權限。 替換佔位符,將查詢參數值以 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>將回傳的
state與您傳送的值進行比對。 確認admin_consent=True此參數存在,且未回傳任何error參數。 錯誤回撥還包括admin_consent=True。 檢查預期租戶,但不要使用回呼中的租戶值來驗證或授權來電者。 關於回應格式,請參閱 Microsoft 身分識別平台 的管理員同意。開啟 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 授權。
在已設定藍圖憑證可用的環境中,從專案目錄執行專案。 受管理身份設定需要一台已設定指定管理身份與聯邦的 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 傳送存取權杖。使用從 將使用者驗證至代理程式 API 的上游客戶端,取得代理程式 API 的存取權杖,並具備所需的委派範圍與
Agent.User角色。 變更指派後申請新的令牌。 在測試 shell 中將其設為AGENT_API_ACCESS_TOKEN環境變數,且不將其記錄在原始碼控制或 shell 歷史中。 不要替換 ID 權杖、Graph 管理權杖或下游自訂 API 權杖。在獨立的 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失敗;此範例不會將下游錯誤轉換為對應的入站狀態碼。重複請求且不使用授權標頭:來自代理程式的 expect
401 Unauthorized。 如果一個本來有效的代理 API 令牌缺少Agent.User,而且該令牌是由租戶簽發,則預期會出現403 Forbidden。 當需要指派時,租用戶可能會先拒絕權杖簽發。在下游 API 中,確認簽章、發行者、受眾、存續時間及所需應用程式角色。 請將
oid已驗證的代幣與代理身份物件 ID(而非藍圖物件 ID)進行比較,並檢查其roles聲明。 請參閱「 在下游 API 中驗證代理程式 ID 令牌」。 單憑成功的代幣回應,並不能證明這些檢查。測試下游 API 拒絕缺少其所需角色的令牌,使用獨立的測試身份或固定裝置,而非移除生產授權。 預期在該 API 會遭到拒絕;不要從代理的例外回應推斷其狀態。
不要記錄存取權杖、憑證斷言或私鑰。 在排除故障時記錄相關 ID 與請求時間。