在 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 永遠不會重複使用該 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 憑證優先順序。
• 為每個環境（正式環境、測試環境）新增個別的聯合規則，以便您可以撤銷其中一個而不影響其他規則。