搭配 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 之間的步驟略有不同。

gcloud run deploy my-service \
  --service-account [email protected]

GET http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full
Metadata-Flavor: Google

gcloud auth print-identity-token \
  --audiences="https://api.anthropic.com" \
  --include-email

{
  "iss": "https://accounts.google.com",
  "aud": "https://api.anthropic.com",
  "sub": "104892...",
  "azp": "104892...",
  "email": "[email protected]",
  "email_verified": true,
  "exp": 1775527120
}



設定 Anthropic

在 Claude Console 中，開啟 Settings → Workload identity，點擊 Connect workload，然後選擇 Google Cloud 圖塊。精靈會引導您完成註冊簽發者、建立服務帳戶和建立聯合規則的流程。

精靈會為您建立這些資源。無論您是在精靈中輸入這些值，還是將其傳送至 Admin API，請使用以下值：

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

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

聯合規則： 同時比對 sub 和 email 宣告。email 是可讀的服務帳戶位址；sub 是服務帳戶的數字唯一 ID，Google 永遠不會重複使用它，因此固定它可以在服務帳戶被刪除、之後又以相同電子郵件建立新帳戶時保護該規則。使用 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。當您提供一個可從中繼資料伺服器回傳新身分權杖的 token-provider 可呼叫物件時，每個 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Cloud Run"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Google 身分權杖大約在一小時後過期。SDK 會在過期前自動重新呼叫 token provider 並重新交換。對於執行時間超過存取權杖 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 權杖，加入諸如 claims.google.compute_engine.project_id == "my-project" 的 condition，將規則限制在單一專案的節點。



後續步驟

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