--- title: 搭配 Google Cloud 使用 WIF url: https://platform.claude.com/docs/zh-TW/manage-claude/wif-providers/gcp description: 使用 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 概念](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation#concepts)：服務帳戶、「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 之間的步驟略有不同。 將專用服務帳戶附加至您的服務或執行個體： ```bash CLI gcloud run deploy my-service \ --service-account inference-worker@my-project.iam.gserviceaccount.com ``` 在工作負載內部，中繼資料伺服器會依需求回傳已簽署的身分權杖。請使用您打算在 Anthropic 端註冊的 `audience` 來請求它，並加上 `format=full`，使回應包含 `email` 宣告： ```text wrap GET http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full Metadata-Flavor: Google ``` 或者，使用 gcloud CLI： ```bash CLI gcloud auth print-identity-token \ --audiences="https://api.anthropic.com" \ --include-email ``` 對應的 SDK 寫法請參閱[取得並使用權杖](https://platform.claude.com/docs/zh-TW/manage-claude/wif-providers/gcp#acquire-and-use-the-token)。 解碼後的權杖酬載如下所示： ```json { "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`。 在您的叢集上啟用 [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)，並使用 `iam.gke.io/gcp-service-account` 註解將您的 Kubernetes 服務帳戶繫結至 Google 服務帳戶： ```yaml apiVersion: v1 kind: ServiceAccount metadata: name: inference-worker namespace: prod annotations: iam.gke.io/gcp-service-account: inference-worker@my-project.iam.gserviceaccount.com ``` 完成此繫結後，GKE 中繼資料伺服器會回傳與 Cloud Run 及 GCE 情況完全相同的 Google 簽署權杖：相同的 `https://accounts.google.com` 簽發者、相同的 `email` 宣告、相同的擷取 URL。請完全依照下一節的方式設定 Anthropic。 來自 GKE 的 `format=full` 權杖還會額外包含 `google.compute_engine.project_id`、`google.compute_engine.zone` 與 `google.compute_engine.instance_name` 宣告，您可以在聯合規則的 `condition` 比對器中引用它們（例如 `claims.google.compute_engine.project_id == "my-project"` 這樣的 CEL 運算式），以將存取範圍限定於特定叢集或節點集區。 如果您不想將 Kubernetes 服務帳戶繫結至 Google 服務帳戶，GKE Pod 可以改用叢集本身的 OIDC 簽發者（`https://container.googleapis.com/v1/projects/PROJECT/locations/REGION/clusters/CLUSTER`）搭配投射的 `serviceAccountToken` 磁碟區。該途徑使用的是每個叢集各自的簽發者，而非 `accounts.google.com`。該模式請參閱[搭配 Kubernetes 使用 WIF](https://platform.claude.com/docs/zh-TW/manage-claude/wif-providers/kubernetes)。 ## 設定 Anthropic 在 Claude Console 中，前往 [Workload identity](https://platform.claude.com/settings/workload-identity-federation) 頁面（`platform.claude.com/settings/workload-identity-federation`），點擊 **Connect workload**，然後選擇 **Google Cloud** 圖塊。精靈會引導您完成註冊簽發者、建立服務帳戶以及建立聯合規則的步驟。 精靈會為您建立這些資源。無論您是在精靈中輸入這些值，還是將它們傳送至 [Admin API](https://platform.claude.com/docs/zh-TW/manage-claude/wif-admin-api)，請使用下列值： **聯合簽發者：** Google 公開發布其 OIDC 探索文件，因此請使用探索模式。這個單一簽發者涵蓋所有 Google Cloud 介面（Cloud Run、GCE、Cloud Functions、App Engine，以及啟用 Workload Identity 的 GKE）。請以規則而非簽發者來區分工作負載。 ```json { "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。 ```json { "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。當您提供 `identity_token_provider` (typescript: `identityTokenProvider`; php: `identityProvider`; csharp: `IdentityTokenProvider`; go: `option.WithFederationTokenProvider`; java: `IdentityTokenConfig`) 時，Claude SDK 會為您處理交換與重新整理的循環，如以下範例所示。除了 Java 之外（請參閱該範例中的註解），該選項接受一個會從中繼資料伺服器傳回新身分權杖的權杖提供者。 ```bash cURL # 從中繼資料伺服器取得由 Google 簽署的身分權杖 JWT=$(curl -sS -H "Metadata-Flavor: Google" \ "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full") # 將其交換為 Anthropic 存取權杖 RESPONSE=$(curl -sS https://api.anthropic.com/v1/oauth/token \ -H "content-type: application/json" \ --data @- < 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-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")) ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; import { oidcFederationProvider } from "@anthropic-ai/sdk/lib/credentials/oidc-federation"; const METADATA_URL = "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full"; async function fetchGoogleIdentityToken(): Promise { const response = await fetch(METADATA_URL, { headers: { "Metadata-Flavor": "Google" } }); return response.text(); } const client = new Anthropic({ credentials: oidcFederationProvider({ identityTokenProvider: fetchGoogleIdentityToken, federationRuleId: process.env.ANTHROPIC_FEDERATION_RULE_ID!, organizationId: process.env.ANTHROPIC_ORGANIZATION_ID!, serviceAccountId: process.env.ANTHROPIC_SERVICE_ACCOUNT_ID, workspaceId: process.env.ANTHROPIC_WORKSPACE_ID, baseURL: "https://api.anthropic.com", fetch }) }); const message = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello from Cloud Run" }] }); for (const block of message.content) { if (block.type === "text") { console.log(block.text); } } ``` ```go Go const audience = "https://api.anthropic.com" googleIDToken := func(ctx context.Context) (string, error) { creds, err := idtoken.NewCredentials(&idtoken.Options{Audience: audience}) if err != nil { return "", err } tok, err := creds.Token(ctx) if err != nil { return "", err } return tok.Value, nil } client := anthropic.NewClient( option.WithFederationTokenProvider(googleIDToken, option.FederationOptions{ FederationRuleID: os.Getenv("ANTHROPIC_FEDERATION_RULE_ID"), OrganizationID: os.Getenv("ANTHROPIC_ORGANIZATION_ID"), ServiceAccountID: os.Getenv("ANTHROPIC_SERVICE_ACCOUNT_ID"), WorkspaceID: os.Getenv("ANTHROPIC_WORKSPACE_ID"), }), ) message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Hello from Cloud Run")), }, }) if err != nil { panic(err) } for _, block := range message.Content { if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok { fmt.Println(textBlock.Text) break } } ``` ```java Java import com.anthropic.config.AuthenticationConfig; import com.anthropic.config.AuthenticationType; import com.anthropic.config.IdentityTokenConfig; import com.anthropic.config.InMemoryProfileConfigProvider; import com.anthropic.config.ProfileConfig; // ... import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; void main() throws Exception { HttpClient http = HttpClient.newHttpClient(); HttpRequest metadataRequest = HttpRequest.newBuilder() .uri(URI.create("http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full")) .header("Metadata-Flavor", "Google") .build(); // Java SDK 接受權杖本身或檔案路徑，而非函式；使用 // source("value") 時，path(...) 存放權杖。SDK 會在每次重新整理 // Anthropic 存取權杖時傳送同一個權杖，一旦該權杖 // 過期，或（若含 jti 宣告）已被使用過，就會失敗。對於長時間執行的 // 程序，請傳入 source("file")，並在每次重新整理前 // 將新權杖寫入該檔案。 String googleIdentityToken = http.send(metadataRequest, HttpResponse.BodyHandlers.ofString()).body(); AnthropicClient client = AnthropicOkHttpClient.builder() .configurationProvider(InMemoryProfileConfigProvider.of(ProfileConfig.builder() .organizationId(System.getenv("ANTHROPIC_ORGANIZATION_ID")) .workspaceId(System.getenv("ANTHROPIC_WORKSPACE_ID")) .authentication(AuthenticationConfig.builder() .type(AuthenticationType.OIDC_FEDERATION) .federationRuleId(System.getenv("ANTHROPIC_FEDERATION_RULE_ID")) .serviceAccountId(System.getenv("ANTHROPIC_SERVICE_ACCOUNT_ID")) .identityToken(IdentityTokenConfig.builder() .source("value") .path(googleIdentityToken) .build()) .build()) .build())) .build(); var message = client.messages().create(MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(1024) .addUserMessage("Hello from Cloud Run") .build()); IO.println(message.content()); } ``` ```csharp C# using Anthropic.Credentials; // ... var credentials = new WorkloadIdentityCredentials(new WorkloadIdentityOptions { FederationRuleId = Environment.GetEnvironmentVariable("ANTHROPIC_FEDERATION_RULE_ID")!, OrganizationId = Environment.GetEnvironmentVariable("ANTHROPIC_ORGANIZATION_ID"), ServiceAccountId = Environment.GetEnvironmentVariable("ANTHROPIC_SERVICE_ACCOUNT_ID"), WorkspaceId = Environment.GetEnvironmentVariable("ANTHROPIC_WORKSPACE_ID"), IdentityTokenProvider = new MetadataTokenProvider(), }); using var client = new AnthropicClient(new ClientOptions { Credentials = credentials }); var message = await client.Messages.Create(new() { Model = Model.ClaudeOpus5_5, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Hello from Cloud Run" }], }); foreach (var block in message.Content) { if (block.Value is TextBlock textBlock) { Console.WriteLine(textBlock.Text); } } class MetadataTokenProvider : IIdentityTokenProvider { private const string METADATA_URL = "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full"; private static readonly HttpClient httpClient = new() { DefaultRequestHeaders = { { "Metadata-Flavor", "Google" } }, }; public async Task GetIdentityTokenAsync(CancellationToken ct = default) { return await httpClient.GetStringAsync(METADATA_URL, ct); } } ``` ```bash CLI # 將 Google 簽署的身分權杖寫入 CLI 可讀取的檔案 ANTHROPIC_IDENTITY_TOKEN_FILE=$(mktemp) curl -sS -H "Metadata-Flavor: Google" \ "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full" \ > "$ANTHROPIC_IDENTITY_TOKEN_FILE" export ANTHROPIC_IDENTITY_TOKEN_FILE # ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID，以及 # ANTHROPIC_SERVICE_ACCOUNT_ID 和 ANTHROPIC_WORKSPACE_ID 會從環境變數中讀取。 ant messages create \ --model claude-opus-5-5 \ --max-tokens 1024 \ --message '{role: user, content: "Hello from Cloud Run"}' ``` ```php PHP use Anthropic\Client; use Anthropic\Lib\Credentials\CredentialResult; use Anthropic\Lib\Credentials\IdentityTokenProvider; use Anthropic\Lib\Credentials\TokenCache; use Anthropic\Lib\Credentials\WorkloadIdentityCredentials; const METADATA_URL = 'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full'; class GoogleIdentityToken implements IdentityTokenProvider { public function getIdentityToken(): string { $context = stream_context_create([ 'http' => ['header' => "Metadata-Flavor: Google\r\n"], ]); return file_get_contents(METADATA_URL, false, $context); } } $credentials = new CredentialResult( provider: new TokenCache(new WorkloadIdentityCredentials( identityProvider: new GoogleIdentityToken(), federationRuleId: getenv('ANTHROPIC_FEDERATION_RULE_ID'), organizationId: getenv('ANTHROPIC_ORGANIZATION_ID'), serviceAccountId: getenv('ANTHROPIC_SERVICE_ACCOUNT_ID'), workspaceId: getenv('ANTHROPIC_WORKSPACE_ID') ?: null, )), ); $client = new Client(credentials: $credentials); $message = $client->messages->create( model: 'claude-opus-5-5', maxTokens: 1024, messages: [['role' => 'user', 'content' => 'Hello from Cloud Run']], ); $textBlock = array_find($message->content, static fn ($block): bool => $block->type === 'text'); echo $textBlock->text, PHP_EOL; ``` ```ruby Ruby require "anthropic" require "net/http" METADATA_URL = "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full" credentials = Anthropic::WorkloadIdentityCredentials.new( identity_token_provider: -> { Net::HTTP.get(URI(METADATA_URL), {"Metadata-Flavor" => "Google"}) }, federation_rule_id: ENV.fetch("ANTHROPIC_FEDERATION_RULE_ID"), organization_id: ENV.fetch("ANTHROPIC_ORGANIZATION_ID"), service_account_id: ENV.fetch("ANTHROPIC_SERVICE_ACCOUNT_ID"), workspace_id: ENV["ANTHROPIC_WORKSPACE_ID"] ) client = Anthropic::Client.new(credentials: credentials) message = client.messages.create( model: "claude-opus-5-5", max_tokens: 1024, messages: [{role: "user", content: "Hello from Cloud Run"}] ) puts message.content.find { it.type == :text }.text ``` Google 身分權杖大約在一小時後到期。除了 Java 之外（請參閱該範例中的註解），SDK 會在到期前自動重新呼叫權杖提供者並重新交換。對於執行時間超過存取權杖 `expires_in` 的 shell 指令碼，請以計時器重新整理並重複交換。 ## 驗證設定 在您的工作負載內部，解碼身分權杖並確認宣告與您的規則相符： ```bash 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`），請在 Claude Console 中查看[驗證歷史記錄頁面](https://platform.claude.com/settings/workload-identity-federation?tab=history)以了解拒絕原因，並參閱[疑難排解失敗的交換](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#troubleshoot-a-failed-exchange)；Google Cloud 端最常見的原因是缺少 `email` 宣告（請使用 `format=full` 請求權杖，以便包含該宣告）。 ## 限定規則範圍 Google 的 `sub` 宣告是服務帳戶的不透明數字唯一 ID， 沒有穩定的前綴。帶有結尾 `*` 的 `subject_prefix` 會比對到 所有 Google Cloud 專案中的任意服務帳戶，而其中任何一個 都可能取得聯合的 Anthropic 權杖。 將規則的 `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](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation) 頁面，了解完整的資源模型與 SDK 憑證優先順序。 * 為每個環境（正式、預備）新增個別的聯合規則，以便您可以撤銷其中一個而不影響其他環境。