使用限定範圍的憑證限制代理權限

當自動化調度管理代理呼叫遠端 Agent2Agent (A2A) 代理時,限定憑證範圍可確保遠端代理只會取得該要求所需的權限。在代理程式登錄檔中找到代理程式後,您可以使用 Agent Identity 驗證管理工具,搭配受限的 OAuth 範圍或 Cloud Storage 的憑證存取權邊界,加入使用者憑證或產生限定範圍的權杖。

事前準備

使用 A2A 呼叫的範圍憑證限制代理程式權限前,請先完成下列步驟:

  1. 設定 Agent Registry。
  2. 如果是單一專案設定,請取得已啟用 Agent Registry 的管理專案 ID。如果您為多個專案設定了管理邊界,請使用管理專案的 ID 進行邊界範圍的探索和註冊,或指定成員專案 ID 進行單一專案作業。

  3. 如要限制 Cloud Storage 權杖,請在專案中啟用 Security Token Service API (sts.googleapis.com)。

  4. 安裝 google-auth 和 requests Python 程式庫:

    pip install --upgrade google-auth requests
    
  5. 為本機開發作業設定應用程式預設憑證 (ADC)。否則,請附加服務帳戶或 Workload Identity Federation 憑證設定:

    gcloud auth application-default login
    

必要的角色

您可以使用使用者帳戶進行本機開發,也可以使用服務帳戶或代理主體,讓自動化調度管理工具代理探索已註冊的代理,並呼叫目標 A2A 代理。使用者帳戶、服務帳戶或代理主體必須具備適當角色,才能完成這些工作。

為確保您的使用者帳戶、服務帳戶或代理主體具備必要權限,可在代理登錄檔中探索 A2A 代理,並呼叫目標 A2A 代理,請要求管理員將下列 IAM 角色授予您的使用者帳戶、服務帳戶或代理主體:

  • 如要在 Agent Registry 探索代理:在已啟用 Agent Registry 的管理專案中,具備 Agent Registry API 檢視者 (roles/agentregistry.viewer) 角色
  • 如要在執行階段呼叫目標 A2A 代理,必須具備託管目標代理的服務執行階段或閘道角色,才能呼叫該代理。舉例來說,如果目標代理在 Cloud Run 執行,帳戶或主體必須具備 Cloud Run 叫用者角色 (roles/run.invoker)。

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

管理員或許也能透過自訂角色或其他預先定義的角色,為您的使用者帳戶、服務帳戶或代理主體授予必要權限。

憑證如何在代理之間傳遞

當 A2A 用戶端或主調度代理將訊息傳送至遠端代理時,下游服務會根據要求的驗證方式檢查權限:

  • 代表使用者:使用者登入您的自動調度管理代理,該代理會將使用者授權的 OAuth 2.0 權杖,或由驗證管理員管理的權杖,傳遞至遠端 A2A 代理。 Google Cloud API 會驗證權杖並檢查使用者的 Identity and Access Management (IAM) 權限,確保遠端代理無法存取使用者無權存取的資源。
  • 使用代理自身的身分:如果協調器代理在沒有使用者登入的情況下執行,會使用自己的代理身分或服務帳戶進行驗證。下游服務會檢查授予該代理主體 (principal://)、相符主體集 (principalSet://) 或其服務帳戶的角色。
  • 從外部或跨雲端工作負載:在Google Cloud 外部執行的代理會透過 Workload Identity Federation,從外部身分識別資訊提供者交換權杖,取得聯合 Google Cloud 存取權杖,然後呼叫目標 Agent Endpoint。

如要限制權杖授予遠端代理的權限,您可以使用繫結限制 OAuth 權杖的範圍,適用於第三方或 SaaS A2A 代理。

您也可以使用憑證存取權邊界限制 Cloud Storage 權杖,將 Google Cloud 存取權杖限制在特定 Cloud Storage bucket 或物件。憑證存取權邊界僅支援 Cloud Storage (storage.googleapis.com) 權限。對於其他 Google Cloud API 和 A2A 代理呼叫,請透過驗證管理工具繫結、具有 IAM 允許和拒絕政策的最小權限代理身分,或 Agent Gateway 控管存取權。

如果這些選項不符合您的用途,且自動化調度管理工具代理程式使用服務帳戶進行驗證,您也可以使用服務帳戶模擬,為專用服務帳戶要求短期權杖,該帳戶僅具備特定工作所需的角色。

使用繫結設定 OAuth 權杖範圍

呼叫使用 2 足式或 3 足式 OAuth 2.0 的第三方或 SaaS A2A 代理時,請在驗證管理工具中建立驗證供應商,並在 Agent Registry 中附加 Binding 資源,其中僅列出遠端代理所需的 OAuth scopes。Agent Development Kit (ADK) 使用 get_remote_a2a_agent() 擷取遠端代理時,會要求僅限該繫結範圍的權杖。如需設定步驟,請參閱「向工具和資源進行驗證」和「管理繫結」。

限制 Cloud Storage 權杖

如果自動化調度管理代理將 OAuth 2.0 存取權杖傳遞給讀取或寫入 Cloud Storage 資料的代理或工具,您可以縮減權杖的權限,只允許存取特定 bucket 或物件前置字串。請使用 Security Token Service 套用憑證存取邊界,再傳送要求:

import google.auth
from google.auth import downscoped
from google.auth.transport.requests import Request

source_creds, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)

access_boundary_rule = downscoped.AccessBoundaryRule(
    available_resource=(
        "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
    ),
    available_permissions=["inRole:roles/storage.objectViewer"],
)
cab = downscoped.CredentialAccessBoundary(rules=[access_boundary_rule])

downscoped_creds = downscoped.Credentials(
    source_credentials=source_creds,
    credential_access_boundary=cab,
)
downscoped_creds.refresh(Request())

將 BUCKET_NAME 替換為遠端代理程式可讀取的 Cloud Storage bucket 名稱。

其他安全控制項目

您可以結合憑證範圍、網路政策和提示檢查:

  • 網路存取政策:透過 Agent Gateway 轉送 A2A 呼叫,對已註冊的 Agent 資源強制執行 Identity-Aware Proxy (IAP) 統一存取政策 (UAP)。
  • 提示詞和回覆檢查:設定 Model Armor 與 Agent Gateway 整合和服務擴充繫結,檢查支援的 A2A 提示詞和回覆,防範提示詞注入和敏感資料外洩。

後續步驟