Claude Platform Docs
管理身分提供者

搭配 Google Cloud 使用 WIF

使用 Google 簽署的身分權杖取代靜態 API 金鑰，將 Google Cloud 工作負載（Cloud Run、Cloud Functions、App Engine、GCE、GKE）聯合至 Claude API。

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

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

先決條件

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

設定 Google Cloud

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

將專用服務帳戶附加至您的服務或執行個體：

CLI
gcloud run deploy my-service \
  --service-account inference-worker@my-project.iam.gserviceaccount.com

在工作負載內部，中繼資料伺服器會依需求回傳已簽署的身分權杖。請使用您打算在 Anthropic 端註冊的 audience 來請求它，並加上 format=full，使回應包含 email 宣告：

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

或者，使用 gcloud CLI：

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

對應的 SDK 寫法請參閱取得並使用權杖。

解碼後的權杖酬載如下所示：

{
  "iss": "https://accounts.google.com",
  "aud": "https://api.anthropic.com",
  "sub": "104892...",
  "azp": "104892...",
  "email": "inference-worker@my-project.iam.gserviceaccount.com",
  "email_verified": true,
  "exp": 1775527120
}

sub 宣告是 Google 服務帳戶的不透明數字唯一 ID。email 宣告是人類可讀的服務帳戶位址。請在您的聯合規則中同時比對 sub 與 email。

設定 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 永遠不會重複使用它，因此固定它可以在服務帳戶被刪除、之後又以相同 email 建立新帳戶時保護該規則。請使用 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": "inference-worker@my-project.iam.gserviceaccount.com"
    }
  },
  "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
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 值。如果交換失敗並回傳不透明的 401 authentication_error 回應（訊息為 Authentication failed），請查看驗證歷史記錄頁面以了解拒絕原因，並參閱疑難排解失敗的交換；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 憑證優先順序。
  • 為每個環境（正式、預備）新增個別的聯合規則，以便您可以撤銷其中一個而不影響其他環境。

Was this page helpful?