使用代理程式本身的 ID 向 Google Cloud 進行驗證

代理可使用自己的身分存取 Google Cloud API 和其他資源。如果代理託管於 Google Cloud，Google 建議使用這個方法與其他 Google Cloud 服務互動。

代理程式自行採取行動時，會使用主要 SPIFFE 身分要求存取權杖。 Google Cloud

事前準備

  1. 確認您選擇了正確的驗證方式。
  2. 建立及部署代理，並啟用代理身分。
  3. 確認您具備完成這項工作所需的角色。

必要的角色

如要取得將 Google Cloud 服務存取權授予代理所需的權限，請要求管理員在目標資源中，授予您下列 IAM 角色：

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

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

授予代理存取權

如要讓代理存取 Google Cloud 服務，您必須在目標資源上，將必要角色授予代理的身分。

在 IAM 允許政策中，代理身分會使用主體 ID。

如要授予代理存取資源的權限，請使用 Google Cloud 控制台或 gcloud CLI。

控制台

  1. 在 Google Cloud 控制台中，前往要授予存取權的資源「IAM」頁面。
    • 如要查看專案的政策，請前往「IAM」(身分與存取權管理) 頁面：

      前往「IAM」頁面

    • 如要查看其他資源，請前往該資源的頁面，然後按一下「權限」或「IAM」分頁標籤。
  2. 按一下 「授予存取權」。
  3. 在「New principals」(新增主體) 欄位中，輸入與您要授予的存取權層級相符的主體 ID：
    • 單一代理： principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • 專案中的所有代理程式： principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • 機構中的所有代理： principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  4. 在「Select a role」(選取角色) 欄位中，搜尋並選取要授予的角色。
  5. 按一下 [儲存]。

Google Cloud CLI

如要授予代理資源存取權，請執行下列指令： 
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

更改下列內容：

  • SERVICE： Google Cloud 服務 (例如 storage 或 bigquery)。
  • RESOURCE_NAME：資源名稱 (例如 bucket 名稱或資料集 ID)。
  • PRINCIPAL_IDENTIFIER：與您要授予的存取層級相符的主體 ID：
    • 單一代理程式：principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • 專案中的所有代理：principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • 組織中的所有代理：principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  • ORGANIZATION_ID：您的 Google Cloud 組織 ID。
  • PROJECT_NUMBER：您的 Google Cloud 專案編號。
  • LOCATION：代理的位置 (例如 us-central1)。(只有單一代理存取權需要)。
  • ENGINE_ID：推論引擎的 ID。(僅限單一代理存取權，才需要此步驟)。
  • ROLE：要授予的 IAM 角色。

在程式碼中參照代理身分

當代理部署至支援的 Google Cloud 環境時， Google Cloud 用戶端程式庫會自動使用 Agent Identity。

下列 Python 程式碼片段說明如何使用 Agent Development Kit (ADK)，手動透過 Agent Identity 憑證呼叫 Cloud Vision API。

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

選用：停用憑證繫結權杖

Google 預設管理的情境感知存取權政策，有助於保護 Agent Identity 憑證。除了 Agent Gateway 之外，這項政策也會驗證代理的存取權杖，強制執行 Demonstrating Proof of Possession (DPoP)。這項政策也要求使用相互傳輸層安全性 (mTLS) 存取 Agent Gateway。這項規定可確保只有預期且受信任的執行階段環境 (例如 Cloud Run 容器或 Google Kubernetes Engine (GKE) Pod)，才能使用憑證繫結權杖。這項安全基準可防止遭竊憑證遭到重播，有助於防範憑證遭竊和帳戶入侵 (ATO)。

憑證繫結有助於保護兩種代理程式憑證：

  • Google Cloud 存取權杖：OAuth 2.0 存取權杖的效期較短，用於驗證對 Google Cloud API 和其他資源 (*.googleapis.com) 的要求。
  • OpenID Connect (OIDC) ID 權杖：JSON Web Token (JWT)， 用於驗證對 外部服務，以及對 託管於 Google Cloud 執行階段 (例如 Cloud Run (*.mtls.run.app) 或 GKE) 的工具和服務提出的要求。

選擇不為所有存取權和 ID 權杖繫結

不建議在執行階段環境中停用預設情境感知存取權政策和憑證繫結權杖。設定 GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false 會移除 Google Cloud 存取權杖和 OIDC ID 權杖的權杖繫結保護，導致這些短期權杖容易遭竊或遭受重送攻擊。

不過，在下列罕見情況下，您可以選擇在整個執行階段環境中停用這項功能：

  • 您對專員之間的權杖共用有特定要求。
  • 您必須直接將權杖插入要求標頭。
  • 代理無法驗證，並傳回 401 UNAUTHENTICATED 錯誤。

如要在整個執行階段環境中停用這項功能，請在部署代理程式時設定下列環境變數：

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

選擇不接收個別 ID 權杖要求

根據預設，支援的 Google Auth 用戶端程式庫會將憑證指紋納入權杖的 cnf (x5t#S256) 宣告，以加密方式將 OIDC ID 權杖繫結至代理程式的專屬 X.509 憑證。

部分服務 (例如 Cloud Run) 會在出現 cnf 聲明時強制執行憑證繫結。如果代理透過非 mTLS 端點 (例如標準 *.run.app 網址) 呼叫這些服務，或目標端點不需要繫結憑證，您可以選擇不要求個別 ID 權杖。這項設定只會影響該要求，不會停用 Google Cloud 存取權杖的憑證繫結。

Python

在 Python google-auth 程式庫 (GKE 2.61.0 以上版本，以及 Cloud Run 2.62.0 以上版本) 中，設定 bind_id_token=False：

from google.auth.transport.requests import AuthorizedSession
from google.auth.transport.requests import Request
from google.oauth2 import id_token

target_audience = "https://TARGET_SERVICE_URL"

# Option 1: Use AuthorizedSession with IDTokenCredentials
credentials = id_token.fetch_id_token_credentials(
    audience=target_audience,
    bind_id_token=False,
)
authed_session = AuthorizedSession(credentials)
response = authed_session.get(target_audience)

# Option 2: Fetch a raw ID token directly
token = id_token.fetch_id_token(
    Request(),
    audience=target_audience,
    bind_id_token=False,
)

將 TARGET_SERVICE_URL 替換為代理呼叫的接收服務目標對象 URI 或網址。

部署代理

將代理部署至 Google Cloud時，請務必啟用 Agent Identity。如要部署至 Gemini Enterprise Agent Platform 的 Agent Runtime ，請使用 identity_type=AGENT_IDENTITY 標記：

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

後續步驟