在 Google Cloud 中使用 WIF

使用 Google 签名的身份令牌(而非静态 API 密钥)将 Google Cloud 工作负载(Cloud Run、Cloud Functions、App Engine、GCE、GKE)联合到 Claude API。

任何能够访问实例元数据服务器的 Google Cloud 计算环境都可以为其附加的服务账号请求一个由 Google 签名的 “identity token”(身份令牌)。这些环境包括 Cloud Run、Cloud Functions、App Engine、Compute Engine (GCE) 以及启用了 Workload Identity 的 Google Kubernetes Engine (GKE)。该令牌的颁发者为 https://accounts.google.com,Anthropic 可以通过标准的 OpenID Connect (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 之间的步骤略有不同。

Cloud Run、Cloud Functions、App Engine、GCE

为您的服务或实例附加一个专用服务账号:

示例代码
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:

示例代码
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。

启用 Workload Identity 的 GKE

在您的集群上启用 GKE Workload Identity,并通过 iam.gke.io/gcp-service-account 注解将您的 Kubernetes 服务账号绑定到 Google 服务账号:

示例代码
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 元数据服务器返回的 Google 签名令牌与 Cloud Run 和 GCE 的情况完全相同。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 匹配器中引用这些声明,该匹配器是一个 “Common Expression Language”(通用表达式语言),即 CEL 表达式,例如 claims.google.compute_engine.project_id == "my-project"。

配置 Anthropic

在 Claude Console 中,前往工作负载身份页面(platform.claude.com/settings/workload-identity-federation),点击连接工作负载,然后选择 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 inference-worker@my-project.iam.gserviceaccount.com --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。当您提供 identity_token_provider (typescript: identityTokenProvider; php: identityProvider; csharp: IdentityTokenProvider; go: option.WithFederationTokenProvider(); java: IdentityTokenConfig) 时,SDK 会为您处理交换和刷新循环,如以下示例所示。如果该选项接受令牌提供程序,请传入一个从元数据服务器返回新身份令牌的提供程序。

示例代码
# 从元数据服务器获取由 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" \
  -d @- <<JSON
{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "$JWT",
  "federation_rule_id": "$ANTHROPIC_FEDERATION_RULE_ID",
  "organization_id": "$ANTHROPIC_ORGANIZATION_ID",
  "service_account_id": "$ANTHROPIC_SERVICE_ACCOUNT_ID",
  "workspace_id": "$ANTHROPIC_WORKSPACE_ID"
}
JSON
)
ACCESS_TOKEN=$(jq -r .access_token <<<"$RESPONSE")

# 调用 Claude API
curl -sS https://api.anthropic.com/v1/messages \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello from Cloud Run"}]
  }'
示例代码
# 将 Google 签名的身份令牌写入 CLI 可读取的文件
export 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"

# ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID 和
# ANTHROPIC_SERVICE_ACCOUNT_ID 从环境变量中读取。
# 对于为所有工作区或多个工作区启用的规则,请将 ANTHROPIC_PROFILE
# 设置为已设置 workspace_id 的联合配置文件。
ant messages create \
  --model claude-opus-5-5 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello from Cloud Run"}'
示例代码
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-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"))
示例代码
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<string> {
  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);
  }
}
示例代码
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 UserMessageParam { 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<string> GetIdentityTokenAsync(CancellationToken ct = default)
    {
        return await httpClient.GetStringAsync(METADATA_URL, ct);
    }
}
示例代码
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
	}
}
示例代码
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());
}
示例代码
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;
示例代码
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::Credentials::WorkloadIdentity.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 身份令牌大约在 1 小时后过期。使用令牌提供程序时,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 值。如果交换失败并返回不透明的 401 authentication_error 响应(消息为 Authentication failed),请在 Claude Console 中查看身份验证历史记录页面以了解拒绝原因。然后参阅排查交换失败。Google Cloud 端最常见的原因是缺少 email 声明。请使用 format=full 请求令牌,以便其包含该声明。

限定规则范围

将规则的 match 块锁定到符合您用例的最小范围:

  • 精确匹配 sub: 在 claims.sub 中设置完整的数字唯一 ID,切勿对 Google 令牌使用 subject_prefix。
  • 固定 email 声明: 在 sub 之外添加 claims.email,使稳定 ID 和可读地址都必须匹配。
  • 固定受众: 将 audience 设置为您从元数据服务器请求的确切值,以便规则拒绝为其他使用方签发的令牌。
  • 在 GKE 上固定项目: 对于 format=full 令牌,添加诸如 claims.google.compute_engine.project_id == "my-project" 的 condition,将规则限制为某一个项目的节点。

后续步骤

  • 阅读工作负载身份联合页面,了解完整的资源模型和 SDK 凭据优先级。
  • 为每个环境(生产、预发布)添加单独的联合规则,以便您可以撤销其中一个而不影响其他环境。
文档内容持续同步更新