註冊您的代理程式,使其能使用 Microsoft Entra ID 驗證並請求存取 API。 此設定會為您的代理程式建立一個身份,該身份由其安裝或複本共享。
此程序使用 Microsoft Graph beta 版本。 對於雲端代理程式,請為其執行時設定認證。 對於安裝在終端使用者裝置上的代理程式,請使用無需憑證的公用用戶端重新導向設定。 你的呼叫教學會標示你需要的章節。
Important
單一實例代理身份目前處於預覽階段。 此預覽版在沒有服務等級協議的情況下提供,不建議用於生產工作負載。 部分功能可能未被支援或功能受限。 欲了解更多資訊,請參閱 線上服務通用授權條款。
Prerequisites
- 已在 Microsoft Graph 中啟用單一執行個體佈建的 Microsoft Entra 租用戶。 在開始之前,請先與您的 Microsoft 代表確認預覽版的可用性及租戶啟用情況。 若要在設定後請求權杖,也請確認是否啟用單一實例驗證;配置與驗證是分別啟用的。
- 授權建立及更新代理程式識別藍圖及代理程式識別的帳戶,例如 Agent ID Administrator。
- 一個獨立的單一租戶公共管理應用程式,並已獲得管理員同意授與 Microsoft Graph 委派權限
AgentIdentityBlueprint.ReadWrite.All和AgentIdentity.ReadWrite.All,或具備設定管理用戶端的權限。 - 一位管理員,可以授權管理應用程式的 Graph 權限。
- 可被指派為藍圖贊助者的使用者物件 ID。 範例中也會將該使用者指定為擁有者。
- 對於互動式登入,適合用戶端類型的重新導向 URI。 對於以瀏覽器為基礎的管理員同意,即使代理程式在執行階段僅使用用戶端憑證時所用的
web重新導向 URI。 - 進行本地機密用戶端測試時,需要 X.509 憑證及其私鑰的安全儲存。 Azure 託管代理程式可以改用管理式身分同盟認證。 純公開用戶端不需要憑證。
- 對於 API 存取,需提供資源應用程式的用戶端 ID,以及代理程式所需的委派權限或應用程式角色的 ID。
請依照下列說明,透過 Microsoft Graph PowerShell 執行 HTTP 範例,或使用能傳送 JSON 請求主體與標頭的 REST 用戶端。 在 REST 用戶端中,將管理權杖作為 Bearer 權杖,在每個 Graph 要求的 Authorization 標頭中傳送。 切勿使用代理程式的執行時存取權杖進行管理請求。
確認管理員交接
在建立物件之前,請就下列交接達成共識。 管理同意與代理程式的執行時 API 同意是分開的核准。
| 誰 | Action | 準備就緒時 |
|---|---|---|
| 租戶管理員及 Microsoft 代表。 | 確認預覽配置與驗證皆已啟用。 | 租戶支援此設定的註冊與令牌請求。 |
| 授權管理員。 | 核准上述列出的管理客戶端兩個 Graph 權限。 | 操作員可以使用兩個已同意的範圍登入該用戶端。 |
| 開發人員或授權操作員。 | 請完成以下註冊步驟。 | 會記錄藍圖物件 ID、代理程式身份物件 ID 及共用用戶端 ID。 |
| API 擁有者與同意管理員。 | 提供 API 識別碼並核准呼叫教學所需的權限。 | 所需的執行時授權會在第一次 API 呼叫前進行驗證。 |
將您的租戶 ID、管理用戶端 ID 及所請求的 API 權限傳送給管理員。 將 識別碼工作表 與設定步驟一併保存。
如果您正在遵循本地 HTTPS 教學,請在瀏覽器登入前確認開發 HTTPS 憑證在您的電腦上是受信任的。 請遵循組織的信任流程,而非停用 TLS 驗證。
設定管理用戶端
管理用戶端讓管理員或授權操作員登入,以建立代理程式的註冊。 它與代理程式的執行時身份是分開的。 現有的 Azure CLI 登入不會建立此管理內容。
在同一租戶中註冊申請。 選取 [僅此組織目錄中的帳戶]。 在 「驗證」下,加入行動 與桌面應用程式 平台並搭配重新導向 URI
http://localhost。在 API 權限下,新增以下 Microsoft Graph > 委派權限:
-
AgentIdentityBlueprint.ReadWrite.All。 -
AgentIdentity.ReadWrite.All。
-
請由已獲授權的系統管理員授與這些權限的同意。 有關管理員同意的資訊,請參閱Microsoft 身分識別平台 中的權限與同意。
安裝 Microsoft Graph PowerShell 驗證模組,然後透過管理應用程式登入。
Connect-MgGraph為已登入的使用者開啟瀏覽器:Install-Module Microsoft.Graph.Authentication -Scope CurrentUser Connect-MgGraph ` -ClientId "<management-app-client-id>" ` -TenantId "<tenant-id>" ` -Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All" ` -ContextScope Process $context = Get-MgContext if (-not $context -or -not $context.Account) { throw "Microsoft Graph sign-in didn't establish a delegated management context. Stop before creating objects." } $context | Select-Object Account, TenantId, ClientId, Scopes確認
Account、ClientId和Scopes識別出預期的操作員、租用戶和管理應用程式,且TenantId同時包含這兩項權限。 如果缺少範圍或再次請求同意,請停止並請授權管理員驗證應用程式註冊及同意後再繼續。
在 Windows 上,如果 Connect-MgGraph 在登入前因出現 A window handle must be configured 而失敗,請對您的自訂管理用戶端使用文件中記載的瀏覽器登入選項:
Set-MgGraphOption -DisableLoginByWAM $true
再次執行相同的 Connect-MgGraph 指令。 這會改變驗證 UI,而非租戶的存取需求;以授權營運商身分完成完整登入,且不要繞過因合規要求而遭拒的情況。 此設定會在 PowerShell 工作階段持續存在。 如果在這次變更之前就啟用了 WAM,完成後再還原。Set-MgGraphOption -DisableLoginByWAM $false
使用 Invoke-MgGraphRequest 執行 HTTP 範例,且不複製或顯示存取權杖。 例如,將 JSON 正文從 「建立藍圖 」複製到 $body,並取代贊助者佔位符:
$body = @'
<JSON-request-body>
'@
$blueprint = Invoke-MgGraphRequest -Method POST `
-Uri "https://graph.microsoft.com/beta/applications" `
-Headers @{ "OData-Version" = "4.0" } `
-ContentType "application/json" -Body $body
$blueprintObjectId = $blueprint.id
$agentClientId = $blueprint.appId
對於後續的請求,請使用每個 HTTP 範例中所示的方法、完整 URI、標頭與 JSON 主體。 不要在 GET 請求時填寫 -Body 。 模組提供授權標頭。 關於指令語法,請參閱 Invoke-MgGraphRequest。
如果註冊或同意被拒絕,請請您的租戶管理員完成此設定。 請勿授予代理程式這些管理權限以繞過授權錯誤。
建立藍圖
藍圖是保存您代理程式驗證設定與憑證的註冊。
建立藍圖,設定
isSingleInstance為true。 請以贊助者的物件 ID 取代<sponsor-user-object-id>。 需要有贊助人;擁有者指派是可選的。本教學請保留
isSingleInstance: true:它會為代理建立一個身分識別,包括其安裝或複本。 此屬性在建立後無法更改。POST https://graph.microsoft.com/beta/applications OData-Version: 4.0 Content-Type: application/json { "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint", "displayName": "Contoso Operations Agent", "signInAudience": "AzureADMyOrg", "isSingleInstance": true, "sponsors@odata.bind": [ "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>" ], "owners@odata.bind": [ "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>" ] }從
201 Created回應中儲存以下值:-
id:藍圖的物件 ID,用於在 Microsoft Graph 中定址它。 -
appId:用於 OAuth 請求的應用程式(用戶端)ID。
-
範例建立一個單租戶藍圖,並將 signInAudience 設為 AzureADMyOrg。
佈建代理程式身分識別
將身分識別與藍圖註冊分開建立。 請直接依照下方請求操作;這種配置不需要藍圖主體。
建立 Agent ID。 設
agentIdentityBlueprintId為藍圖 的物件 ID,而非其appId。POST https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity OData-Version: 4.0 Content-Type: application/json { "displayName": "Contoso Operations Agent", "agentIdentityBlueprintId": "<blueprint-object-id>", "sponsors@odata.bind": [ "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>" ] }從
201 Created回應中儲存身份的id。 這是代理身分的物件 ID,而非藍圖物件 ID 或 OAuth 用戶端 ID。讀取身分識別資料以驗證結果:
GET https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-object-id>?$select=id,appId,displayName,agentIdentityBlueprintId,instanceMode檢查回傳的值:
屬性 預期值 @odata.type#microsoft.graph.agentIdentity。appId藍圖的 appId。agentIdentityBlueprintId藍圖的物件 ID。 instanceModesingleInstance。
不要為每個安裝、程序或使用者工作階段配置新的身份。 它們使用相同的客戶端 ID。
設定重新導向 URI
對於授權碼流程,請在與用戶端相符的平台上註冊重定向 URI。 機密客戶端使用 web;公開客戶端使用 publicClient。
基於瀏覽器的管理員同意程序也需要重新web導向 URI,即使是僅在執行時使用用戶端憑證的代理程式也是如此。 重定向處理的是同意回調,而非用戶端憑證令牌請求。 僅當不需要授權碼流程或瀏覽器管理員同意時,才可跳過此節。
請閱讀目前的重新導向設定:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClient更新適當的重新導向集合。 以下範例顯示兩種用戶端類型;只包含您的代理所使用的平台。 保留所有仍需要的現有重新導向 URI。
PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id> OData-Version: 4.0 Content-Type: application/json { "@odata.type": "#microsoft.graph.agentIdentityBlueprint", "web": { "redirectUris": [ "https://agent.contoso.com/signin" ] }, "publicClient": { "redirectUris": [ "http://localhost" ] } }成功更新後會回傳
204 No Content。 重新導向的 URI 集合會被取代,而非附加。 請勿在未保留 URI 的情況下將此範例複製到現有配置上。
同一份藍圖可以同時註冊兩個平台。 每個授權請求都會使用其用戶端類型的重新導向 URI。 公開客戶端不會傳送憑證,即使機密元件使用同一藍圖上的憑證。 不要為了在這些授權碼情境間切換而變更 isFallbackPublicClient。
為機密用戶端新增憑證
對於本地機密客戶端測試,請僅在應用程式上註冊公開憑證。 執行階段會保留私鑰用於驗證。
若為僅限公開用戶端,請跳過此部分。 對於使用 Azure 託管代理程式並使用託管身分聯盟的代理程式,請先設定聯合認證,然後繼續「宣告 API 權限」。
對於 Windows 開發機器,您可以建立自簽憑證,並將其匯出其公開憑證及受密碼保護的 PFX。 把 PFX 放在來源樹之外。 以下請使用 Base64 編碼的 DER 公開憑證 key ,而非 PFX 或 PEM 檔案的標頭與頁尾。 例如:
$publicCertificate = Get-PfxCertificate -FilePath "<absolute-path-to-public-cer>"
$publicCertificateBase64 = [Convert]::ToBase64String($publicCertificate.RawData)
貼 $publicCertificateBase64 到註冊請求中。 公開值不是認證資訊;PFX 及其密碼才是。 非 Windows 開發或生產環境,請使用貴組織的憑證發放與私鑰儲存流程。
閱讀目前的憑證集合:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentials新增您的公開憑證,同時保留仍然需要的現有金鑰憑證。 以下申請顯示初始註冊且無現有憑證:
PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id> OData-Version: 4.0 Content-Type: application/json { "@odata.type": "#microsoft.graph.agentIdentityBlueprint", "keyCredentials": [ { "type": "AsymmetricX509Cert", "usage": "Verify", "key": "<base64-encoded-DER-certificate>", "displayName": "Contoso Operations Agent certificate" } ] }成功更新後會回傳
204 No Content。 切勿上傳私鑰,或透過公開用戶端散發私鑰。
有關憑證格式與用戶端聲明指引,請參閱 Microsoft 身分識別平台 憑證認證。
宣告 API 權限
只宣告代理程式所需的權限。 使用 Scope 作為委派權限,並使用 Role 作為應用程式權限。 這些 resourceAccess 值是資源應用程式所暴露的權限 ID,而非權限名稱。
請閱讀目前的聲明:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccess新增資源與權限條目,保留仍需使用的現有宣告。 範例顯示一個委派權限和一個應用程式權限。如果你的代理程式不需要,就把任一條目移除。
PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id> OData-Version: 4.0 Content-Type: application/json { "@odata.type": "#microsoft.graph.agentIdentityBlueprint", "requiredResourceAccess": [ { "resourceAppId": "<resource-app-id>", "resourceAccess": [ { "id": "<delegated-permission-id>", "type": "Scope" }, { "id": "<app-role-id>", "type": "Role" } ] } ] }成功更新後會回傳
204 No Content。
這些聲明不會授與存取權限。 使用者或管理員同意會授予委派權限,而管理員則授予應用程式權限。 授權直接屬於代理人 ID。
如果代理程式同時接收來自前端應用程式的呼叫,請 在藍圖中公開識別碼 URI 及委派範圍。 保留所有現有的 API 範圍,並將 requestedAccessTokenVersion 設為 2。 前端會請求該範圍取得一個令牌,其受眾為共用用戶端 ID。
排解 Graph 請求
如果請求失敗,請先檢查 HTTP 狀態及 Graph 錯誤回應,然後再變更權限或重試操作。
| 回應 | 支票 |
|---|---|
400 Bad Request |
閱讀 error.code 並 error.message。 檢查端點的請求結構描述、必要的贊助參考、物件 ID 及屬性值。 |
401 Unauthorized |
取得有效的 Microsoft Graph 存取權杖,並在 Authorization 標頭中傳送。 |
403 Forbidden |
確認管理應用程式具備所需的委派權限與管理員同意,已登入的使用者已授權執行此操作,且租戶已啟用預覽版。 |
詳細資訊請參閱 Microsoft Graph 錯誤回應。 當您聯絡管理員或 Microsoft 支援時,請包含 HTTP 狀態、錯誤代碼及request-id回應標頭。 不要包含存取權杖或其他憑證。
下一步
回到帶你來到這裡的教學課程:
- 驗證使用者以存取 ASP.NET Core 代理 API。
- 以 ASP.NET Core 代理程式呼叫自訂 API。
- 設定 Auth SDK sidecar 元件。
- 讓使用者透過終端使用者裝置上的代理程式登入。
關於直接的 OAuth 請求以及此設定背後的身份模型,請參閱驗證代理身份與代理身份藍圖實例模式。