在 Google Cloud 中使用 WIF

任何可存取執行個體中繼資料伺服器的 Google Cloud 運算環境（Cloud Run、Cloud Functions、App Engine、Compute Engine (GCE)，以及啟用 Workload Identity 的 GKE）都可以為其附加的服務帳戶請求 Google 簽署的身分權杖。該權杖的簽發者為 https://accounts.google.com，Anthropic 可透過標準 OIDC 探索直接驗證，無需額外的 Google Cloud 設定。

本指南說明如何向 Anthropic 註冊 Google 簽發者、將 Google 服務帳戶繫結至 Anthropic 服務帳戶，並讓您的工作負載將其身分權杖交換為短期有效的 Claude API 存取權杖。

先決條件

• 熟悉 WIF 概念：服務帳戶、聯合簽發者和聯合規則。
• 擁有一個 Google Cloud 專案，其中有工作負載在 Cloud Run、Cloud Functions、App Engine、Compute Engine 或 GKE 上執行。
• 已將使用者管理的 Google 服務帳戶附加至該工作負載（而非 Compute Engine 預設服務帳戶）。
• 具有在 Claude Console 中為您的 Anthropic 組織建立服務帳戶、聯合簽發者和聯合規則的權限。

設定 Google Cloud

Google 會自動為任何附加服務帳戶的工作負載簽發身分權杖。除了附加正確的服務帳戶外，Google 端無需啟用任何設定，但標準運算環境與 GKE 之間的步驟略有不同。

設定 Anthropic

依照設定逐步說明在 Claude Console 中註冊聯合簽發者、建立 Anthropic 服務帳戶，並建立聯合規則。請使用以下 Google Cloud 專屬的值。

聯合簽發者： Google 公開發布其 OIDC 探索文件，因此請使用探索模式。這個單一簽發者涵蓋所有 Google Cloud 介面（Cloud Run、GCE、Cloud Functions、App Engine，以及啟用 Workload Identity 的 GKE）。請使用規則而非簽發者來區分工作負載。

{
  "name": "gcp",
  "issuer_url": "https://accounts.google.com",
  "jwks_source": "discovery"
}

聯合規則： 同時比對 sub 和 email 宣告。email 是可讀的服務帳戶位址；sub 是服務帳戶的數字唯一 ID，Google 永遠不會重複使用該 ID，因此固定此值可在服務帳戶被刪除、之後又以相同電子郵件建立新帳戶時保護規則。使用 gcloud iam service-accounts describe SA_EMAIL --format='value(uniqueId)' 來查詢唯一 ID。

{
  "name": "gcp-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "audience": "https://api.anthropic.com",
    "claims": {
      "sub": "104892101234567890123",
      "email": "[email protected]"
    }
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

取得並使用權杖

在您的 Google Cloud 工作負載內部，從中繼資料伺服器擷取身分權杖，在 POST /v1/oauth/token 進行交換，並使用傳回的 bearer 權杖呼叫 Claude API。當您提供一個可從中繼資料伺服器傳回新身分權杖的權杖提供者可呼叫物件時，每個 Anthropic SDK 都會為您處理交換和更新迴圈，如以下範例所示。

import os
import anthropic
import google.auth.transport.requests
import google.oauth2.id_token
from anthropic import WorkloadIdentityCredentials

AUDIENCE = "https://api.anthropic.com"


def fetch_google_identity_token() -> str:
    request = google.auth.transport.requests.Request()
    return google.oauth2.id_token.fetch_id_token(request, AUDIENCE)


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=fetch_google_identity_token,
        federation_rule_id=os.environ["ANTHROPIC_FEDERATION_RULE_ID"],
        organization_id=os.environ["ANTHROPIC_ORGANIZATION_ID"],
        service_account_id=os.environ["ANTHROPIC_SERVICE_ACCOUNT_ID"],
        workspace_id=os.environ.get("ANTHROPIC_WORKSPACE_ID"),
    ),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Cloud Run"}],
)
print(message.content[0].text)

Google 身分權杖大約在一小時後過期。SDK 會在過期前自動重新呼叫權杖提供者並重新交換。對於執行時間超過存取權杖 expires_in 的 shell 指令碼，請使用計時器進行更新並重複交換。

驗證設定

在您的工作負載內部，解碼身分權杖並確認宣告與您的規則相符：

curl -sS -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full" \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

檢查 iss 是否為 https://accounts.google.com、aud 是否為 https://api.anthropic.com，以及 email 是否與您聯合規則中的值相符。然後執行上一節中的交換。成功的交換會傳回以 sk-ant-oat01- 開頭的 access_token 以及以秒為單位的 expires_in 值。若出現 400 invalid_grant，請參閱疑難排解交換失敗；Google Cloud 端最常見的原因是缺少 email 宣告（請使用 format=full 請求權杖以包含該宣告）。

限定規則範圍

將規則的 match 區塊鎖定至符合您使用案例的最窄範圍：

• 精確比對 sub： 在 claims.sub 中設定完整的數字唯一 ID，且絕不對 Google 權杖使用 subject_prefix。
• 固定 email 宣告： 在 sub 旁加入 claims.email，使穩定 ID 和可讀位址都必須相符。
• 固定 audience： 將 audience 設定為您從中繼資料伺服器請求的確切值，以拒絕為其他使用者產生的權杖。
• 在 GKE 上固定專案： 對於 format=full 權杖，新增 condition（例如 claims.google.compute_engine.project_id == "my-project"）以將規則限制於單一專案的節點。

後續步驟

• 閱讀 Workload Identity Federation 頁面，了解完整的資源模型和 SDK 憑證優先順序。
• 為每個環境（正式環境、預備環境）新增獨立的聯合規則，以便撤銷其中一個時不影響其他規則。