在 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 之间的步骤略有不同。

配置 Anthropic

按照设置演练在 Claude Console 中注册联合颁发者、创建 Anthropic 服务账号并创建联合规则。请使用以下 Google Cloud 特定的值。

联合颁发者： Google 公开发布其 OIDC 发现文档，因此请使用发现模式。这一个颁发者即可覆盖所有 Google Cloud 平台（Cloud Run、GCE、Cloud Functions、App Engine 以及启用了 Workload Identity 的 GKE）。请通过规则而非颁发者来区分不同的工作负载。

{
  "name": "gcp",
  "issuer_url": "https://accounts.google.com",
  "jwks_source": "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 设置为您从元数据服务器请求的确切值，以便拒绝为其他使用方生成的令牌。
• 在 GKE 上固定项目： 对于 format=full 令牌，添加诸如 claims.google.compute_engine.project_id == "my-project" 之类的 condition，以将规则限制为单个项目的节点。

后续步骤

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