在 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。当您提供一个从元数据服务器返回新身份令牌的令牌提供者可调用对象时，每个 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 会在过期前自动重新调用令牌提供者并重新交换。对于运行时间超过访问令牌 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 设置为您从元数据服务器请求的确切值，以便拒绝为其他使用者铸造的令牌。
• 在 GKE 上固定项目： 对于 format=full 令牌，添加诸如 claims.google.compute_engine.project_id == "my-project" 之类的 condition，将规则限制到单个项目的节点。



后续步骤

• 阅读 Workload Identity Federation 页面，了解完整的资源模型和 SDK 凭证优先级。
• 为每个环境（生产、预发布）添加单独的联合规则，以便您可以撤销其中一个而不影响其他规则。