使用 Microsoft Graph(預覽版)為您的代理程式建立身分

註冊您的代理程式,使其能使用 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 登入不會建立此管理內容。

  1. 在同一租戶中註冊申請。 選取 [僅此組織目錄中的帳戶]。 在 「驗證」下,加入行動 與桌面應用程式 平台並搭配重新導向 URI http://localhost。

  2. 在 API 權限下,新增以下 Microsoft Graph > 委派權限:

    • AgentIdentityBlueprint.ReadWrite.All。
    • AgentIdentity.ReadWrite.All。
  3. 請由已獲授權的系統管理員授與這些權限的同意。 有關管理員同意的資訊,請參閱Microsoft 身分識別平台 中的權限與同意。

  4. 安裝 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。

如果註冊或同意被拒絕,請請您的租戶管理員完成此設定。 請勿授予代理程式這些管理權限以繞過授權錯誤。

建立藍圖

藍圖是保存您代理程式驗證設定與憑證的註冊。

  1. 建立藍圖,設定 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>"
      ]
    }
    
  2. 從 201 Created 回應中儲存以下值:

    • id:藍圖的物件 ID,用於在 Microsoft Graph 中定址它。
    • appId:用於 OAuth 請求的應用程式(用戶端)ID。

範例建立一個單租戶藍圖,並將 signInAudience 設為 AzureADMyOrg。

佈建代理程式身分識別

將身分識別與藍圖註冊分開建立。 請直接依照下方請求操作;這種配置不需要藍圖主體。

  1. 建立 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>"
      ]
    }
    
  2. 從 201 Created 回應中儲存身份的 id。 這是代理身分的物件 ID,而非藍圖物件 ID 或 OAuth 用戶端 ID。

  3. 讀取身分識別資料以驗證結果:

    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。
    instanceMode singleInstance。

不要為每個安裝、程序或使用者工作階段配置新的身份。 它們使用相同的客戶端 ID。

設定重新導向 URI

對於授權碼流程,請在與用戶端相符的平台上註冊重定向 URI。 機密客戶端使用 web;公開客戶端使用 publicClient。

基於瀏覽器的管理員同意程序也需要重新web導向 URI,即使是僅在執行時使用用戶端憑證的代理程式也是如此。 重定向處理的是同意回調,而非用戶端憑證令牌請求。 僅當不需要授權碼流程或瀏覽器管理員同意時,才可跳過此節。

  1. 請閱讀目前的重新導向設定:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClient
    
  2. 更新適當的重新導向集合。 以下範例顯示兩種用戶端類型;只包含您的代理所使用的平台。 保留所有仍需要的現有重新導向 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 開發或生產環境,請使用貴組織的憑證發放與私鑰儲存流程。

  1. 閱讀目前的憑證集合:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentials
    
  2. 新增您的公開憑證,同時保留仍然需要的現有金鑰憑證。 以下申請顯示初始註冊且無現有憑證:

    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,而非權限名稱。

  1. 請閱讀目前的聲明:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccess
    
  2. 新增資源與權限條目,保留仍需使用的現有宣告。 範例顯示一個委派權限和一個應用程式權限。如果你的代理程式不需要,就把任一條目移除。

    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回應標頭。 不要包含存取權杖或其他憑證。

下一步

回到帶你來到這裡的教學課程:

關於直接的 OAuth 請求以及此設定背後的身份模型,請參閱驗證代理身份與代理身份藍圖實例模式。