在 SPIFFE 中使用 WIF

使用来自 SPIRE 或任何其他 SPIFFE 兼容签发方的 JWT-SVID 将 SPIFFE 工作负载认证到 Claude API。

SPIFFE 是 CNCF 为工作负载签发身份的标准。SPIRE 是其开源参考实现，多个商业产品也签发 SPIFFE 兼容的身份。Anthropic 与任何发出 OIDC 兼容 JWT-SVID 的 SPIFFE 实现联合。联合可以通过公共 HTTPS URL 的 OIDC 发现文档（discovery 模式；参阅 URL 约束）或直接注册 JWKS（inline 模式）来实现。JWT-SVID 规范将 sub 定义为工作负载的 SPIFFE ID，SPIFFE Workload API 要求调用者在获取时提供 aud，因此这些声明在各实现中是相同的。Anthropic 还要求 iss 和 iat，而 JWT-SVID 规范并未强制要求这两个字段，因此请配置你的实现来填充它们（在 SPIRE 中，iss 是 jwt_issuer 服务器设置，iat 会自动设置）。有了这些，本指南的配置 Anthropic、获取并使用令牌和限定规则范围部分适用于任何 SPIFFE 实现。有关当前列表，请参阅 SPIFFE 项目网站上的实现 SPIFFE 的商业软件。

SPIFFE 为每个工作负载分配一个格式为 spiffe://<trust-domain>/ 的稳定身份 URI，SPIRE 通过 Workload API 按需将该身份签发为 JWT-SVID。JWT-SVID 是普通的签名 JWT，其 sub 声明是工作负载的 SPIFFE ID，aud 声明由工作负载在获取时提供。

从 SPIRE 信任域到标准 OIDC 的桥梁是 SPIRE OIDC Discovery Provider，一个独立的辅助程序，为信任域的 JWT 签名密钥发布 /.well-known/openid-configuration 和 JWKS 端点。有了发现提供者，JWT-SVID 的验证方式与其他任何 OIDC 令牌相同：将发现 URL 注册为联合签发方，编写匹配工作负载 SPIFFE ID 的联合规则，然后让工作负载将其 JWT-SVID 出示给 Anthropic 的令牌交换端点。

本页的示例使用 SPIRE，适用于 SPIRE Agent 运行的任何地方：Kubernetes Pod、虚拟机和裸金属主机。

前置条件

• 熟悉 WIF 概念：服务账号、联合签发方和联合规则。
• 一个已签发工作负载身份的 SPIFFE 部署（本页示例使用 SPIRE Server 和 Agent），以及需要调用 Claude API 的工作负载的注册条目。
• 信任域的 OIDC 发现端点（在 SPIRE 中为 OIDC Discovery Provider），运行在可公开访问的 HTTPS 端点上，或者已导出 JWKS 用于 inline 注册。
• 你的 SPIFFE 签发方配置为在 JWT-SVID 上将 iss 声明设置为你将注册为联合签发方 issuer_url 的值。对于 discovery 模式，这是发现端点的公共 URL（在 SPIRE 中为 jwt_issuer 服务器设置）。
• JWT-SVID 可供你的工作负载使用。WIF 仅接受 JWT-SVID；X.509-SVID 不被使用。
• 拥有在 Claude Console 中为你的 Anthropic 组织创建服务账号、联合签发方和联合规则的权限。

获取 JWT-SVID 时请求的受众值始终为 https://api.anthropic.com。在 spiffe-helper 的 jwt_audience、Workload API FetchJWTSVID 调用和联合规则的 audience 匹配器中使用此值。

配置 SPIRE

本节的说明是 SPIRE 特定的。如果你使用不同的 SPIFFE 签发方，请按照其文档配置其 OIDC 发现端点和 JWT-SVID 检索，然后继续配置 Anthropic。

如果你已经在运行带有 OIDC Discovery Provider 的 SPIRE，与 Anthropic 联合需要在 SPIRE 侧完成三件事：一个与发现 URL 匹配的 jwt_issuer、一个将调用 Claude API 的工作负载的注册条目，以及让该工作负载使用 Anthropic 受众获取 JWT-SVID 的方式。以下小节逐一介绍。配置片段仅显示与 Anthropic 联合相关的设置；它们不是完整的 SPIRE 部署配置。

验证 JWT 签发方

Anthropic 通过将 JWT-SVID 的 iss 声明与注册的联合签发方匹配，并从该签发方的发现文档获取 JWKS 来验证 JWT-SVID。两个 SPIRE 设置必须在同一 URL 上达成一致：SPIRE Server 的 jwt_issuer（成为每个铸造的 JWT-SVID 中的 iss 声明）和 OIDC Discovery Provider 的 domains 列表（决定发现文档和 JWKS 的服务主机）。该共享 URL 就是你向 Anthropic 注册的 URL。

信任域和签发方 URL 是独立的。信任域（spiffe://prod.example.com）限定 sub 声明的范围；签发方 URL（https://oidc-discovery.prod.example.com）是 Anthropic 获取签名密钥的地方。它们不需要共享主机名。

确认 jwt_issuer 在 SPIRE Server 的配置中已设置并指向发现提供者的公共 URL。以下示例还展示了默认的 JWT-SVID 生命周期；SPIRE 的内置默认值为 5 分钟，足够短以至于需要持续轮换（参阅运行 spiffe-helper）。Anthropic 的令牌交换端点会拒绝任何生命周期超过联合签发方配置的最大值的标识令牌（默认为 1 小时；参阅验证规则）。此检查适用于每个 SPIFFE 实现，不仅仅是 SPIRE，因此请将 default_jwt_svid_ttl（或任何每个条目的覆盖值）保持在该最大值或以下。

server {
    trust_domain         = "prod.example.com"
    jwt_issuer           = "https://oidc-discovery.prod.example.com"
    default_jwt_svid_ttl = "5m"
    # ...
}

在 OIDC Discovery Provider 的配置中，相同的主机名必须出现在 domains 下，且提供者必须能够访问 SPIRE Server 的 API 套接字。提供者通过 HTTPS 提供发现文档和 JWKS；使用其内置的 ACME 支持终止 TLS，或在其前面放置一个执行 TLS 终止的负载均衡器。

domains = ["oidc-discovery.prod.example.com"]

server_api {
    address = "unix:///run/spire/sockets/private/api.sock"
}

acme {
    email        = "platform@example.com"
    tos_accepted = true
}

注册工作负载

每个调用 Claude API 的工作负载都需要一个 SPIRE 注册条目，将其运行时选择器映射到 SPIFFE ID。如果工作负载已注册，请记下其 SPIFFE ID；你将在联合规则的 subject_prefix 中使用它。如果没有，请注册它。对于 Kubernetes Pod，选择器通常是命名空间和 Kubernetes 服务账号：

spire-server entry create \
    -spiffeID spiffe://prod.example.com/ns/inference/sa/worker \
    -parentID spiffe://prod.example.com/spire/agent/k8s_psat/prod-cluster/NODE_UID \
    -selector k8s:ns:inference \
    -selector k8s:sa:worker

Kubernetes 外部的工作负载使用主机级选择器，如 unix:uid:1000（unix:path 也可用，但需要在代理的 unix workload attestor 配置中设置 discover_workload_path = true）。运行 spire-controller-manager 的集群可以使用 ClusterSPIFFEID 自定义资源声明条目，而不是直接调用 spire-server entry create。

运行 spiffe-helper

spiffe-helper 是一个 sidecar 工具，连接到 SPIRE Agent 套接字，为给定受众获取 JWT-SVID，将其写入文件，并在过期前重新获取。该辅助程序默认以守护进程模式运行；下面的示例显式设置了 daemon_mode = true。

agent_address = "/run/spire/sockets/agent.sock"
cert_dir      = "/var/run/secrets/anthropic.com"
daemon_mode   = true

jwt_svids = [{
    jwt_audience       = "https://api.anthropic.com"
    jwt_svid_file_name = "token"
}]

在 Kubernetes 中，将 spiffe-helper 作为 sidecar 容器运行，与你的应用容器共享基于内存的 emptyDir 卷（medium: Memory），这样 Bearer SVID 永远不会落盘。将 SPIRE Agent 套接字从主机挂载到 sidecar 中，在两个容器中将共享卷挂载到 /var/run/secrets/anthropic.com，并在应用容器上设置 ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token。在 VM 和裸金属上，将 spiffe-helper 作为系统服务与工作负载一起运行，并将两者指向共享目录。

配置 Anthropic

按照设置指南在 Claude Console 中注册联合签发方、创建 Anthropic 服务账号并创建联合规则。使用以下 SPIFFE 特定的值。

联合签发方： 以 discovery 模式注册 OIDC Discovery Provider 的公共 URL。Anthropic 从此 URL 获取 /.well-known/openid-configuration，并按照返回的 jwks_uri 检索信任域的签名密钥。

{
  "name": "spire-prod",
  "issuer_url": "https://oidc-discovery.prod.example.com",
  "jwks": { "type": "discovery" }
}

如果发现提供者无法从公共互联网访问，请自行获取 JWKS（curl https://oidc-discovery.prod.example.com/keys），并使用返回的 keys 数组的内容以 "jwks": {"type": "inline", "keys": [...]} 注册签发方。在 inline 模式下，issuer_url 仅与 JWT-SVID 的 iss 声明进行比较；Anthropic 永远不会尝试访问它。

要在不暴露公共发现端点的情况下自动化 JWKS 更新，请配置 SPIRE Server BundlePublisher 插件（aws_s3、gcp_cloudstorage 或 k8s_configmap），设置 format = "jwks" 以在每次轮换时将 JWT 签名密钥推送到外部存储，然后将其同步到签发方的内联密钥中。

联合规则： 匹配 JWT-SVID 的 sub（SPIFFE ID）和你配置 spiffe-helper 请求的 aud。SPIFFE ID 是 URI 字符串，subject_prefix 将其作为不透明文本匹配，因此精确值或末尾带 * 的前缀匹配都适用。对于更复杂的模式，使用 CEL condition。

{
  "name": "spire-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "spiffe://prod.example.com/ns/inference/sa/worker",
    "audience": "https://api.anthropic.com"
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

尽可能精确地匹配工作负载。只有当该路径下注册的每个工作负载都需要映射到同一个 Anthropic 服务账号时，才将 subject_prefix 放宽为 spiffe://prod.example.com/ns/inference/*。将规则的 fdrl_... ID 添加到工作负载的 ANTHROPIC_FEDERATION_RULE_ID 环境变量中。

获取并使用令牌

Anthropic SDK 可以从 spiffe-helper 维护的文件中读取 JWT-SVID，也可以通过令牌提供者可调用对象直接调用 SPIFFE Workload API。文件路径是最简单的集成方式，适用于每种 SDK 语言；可调用路径去除了 sidecar，但需要在你的应用程序语言中使用 SPIFFE Workload API 客户端。

JWT=$(cat "$ANTHROPIC_IDENTITY_TOKEN_FILE")

ACCESS_TOKEN=$(curl -sS https://api.anthropic.com/v1/oauth/token \
  -H "content-type: application/json" \
  --data @- <<JSON | jq -r .access_token
{
  "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
)

curl https://api.anthropic.com/v1/messages \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }' | jq -r '.content[0].text'

import anthropic

# 读取 spiffe-helper 写入 ANTHROPIC_IDENTITY_TOKEN_FILE 的 JWT-SVID，
# 以及 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、
# ANTHROPIC_SERVICE_ACCOUNT_ID 和 ANTHROPIC_WORKSPACE_ID。
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

// 读取 spiffe-helper 写入 ANTHROPIC_IDENTITY_TOKEN_FILE 的 JWT-SVID，
// 以及 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、
// ANTHROPIC_SERVICE_ACCOUNT_ID 和 ANTHROPIC_WORKSPACE_ID。
const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }]
});
for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

package main

import (
	"context"
	"fmt"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	// 读取 spiffe-helper 写入 ANTHROPIC_IDENTITY_TOKEN_FILE 的 JWT-SVID，
	// 以及 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、
	// ANTHROPIC_SERVICE_ACCOUNT_ID 和 ANTHROPIC_WORKSPACE_ID。
	client := anthropic.NewClient()

	message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     anthropic.ModelClaudeSonnet4_6,
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),
		},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(message.Content[0].Text)
}

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    var message = client.messages().create(MessageCreateParams.builder()
            .model(Model.CLAUDE_SONNET_4_6)
            .maxTokens(1024)
            .addUserMessage("Hello, Claude")
            .build());

    IO.println(message.content());
}

using Anthropic.Models.Messages;
using Anthropic.Oidc;

var result = AnthropicCredentials.Resolve()
    ?? throw new InvalidOperationException("No federation credentials found in environment");
using var client = new AnthropicOidcClient(result);

var message = await client.Messages.Create(new()
{
    Model = Model.ClaudeSonnet4_6,
    MaxTokens = 1024,
    Messages = [new() { Role = Role.User, Content = "Hello, Claude" }],
});
foreach (var block in message.Content)
{
    if (block.Value is TextBlock textBlock)
    {
        Console.WriteLine(textBlock.Text);
    }
}

# 读取 spiffe-helper 写入 ANTHROPIC_IDENTITY_TOKEN_FILE 的 JWT-SVID，
# 以及 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、
# ANTHROPIC_SERVICE_ACCOUNT_ID 和 ANTHROPIC_WORKSPACE_ID。
ant messages create \
  --model claude-sonnet-4-6 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

<?php
require 'vendor/autoload.php';

use Anthropic\Client;

// 读取 spiffe-helper 写入 ANTHROPIC_IDENTITY_TOKEN_FILE 的 JWT-SVID，
// 以及 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、
// ANTHROPIC_SERVICE_ACCOUNT_ID 和 ANTHROPIC_WORKSPACE_ID。
$client = new Client();

$message = $client->messages->create(
    model: 'claude-sonnet-4-6',
    maxTokens: 1024,
    messages: [['role' => 'user', 'content' => 'Hello, Claude']],
);
echo $message->content[0]->text, PHP_EOL;

require "anthropic"

# 读取 spiffe-helper 写入 ANTHROPIC_IDENTITY_TOKEN_FILE 的 JWT-SVID，
# 以及 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、
# ANTHROPIC_SERVICE_ACCOUNT_ID 和 ANTHROPIC_WORKSPACE_ID。
client = Anthropic::Client.new

message = client.messages.create(
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}]
)
puts message.content.first.text

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/option"
	"github.com/spiffe/go-spiffe/v2/svid/jwtsvid"
	"github.com/spiffe/go-spiffe/v2/workloadapi"
)

func main() {
	const audience = "https://api.anthropic.com"

	ctx := context.Background()
	source, err := workloadapi.NewJWTSource(ctx)
	if err != nil {
		panic(err)
	}
	defer source.Close()

	fetchJWTSVID := func(ctx context.Context) (string, error) {
		svid, err := source.FetchJWTSVID(ctx, jwtsvid.Params{Audience: audience})
		if err != nil {
			return "", err
		}
		return svid.Marshal(), nil
	}

	client := anthropic.NewClient(
		option.WithFederationTokenProvider(fetchJWTSVID, 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(ctx, anthropic.MessageNewParams{
		Model:     anthropic.ModelClaudeSonnet4_6,
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),
		},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(message.Content[0].Text)
}

import os
import anthropic
from anthropic import WorkloadIdentityCredentials
from spiffe import JwtSource

AUDIENCE = "https://api.anthropic.com"

# 连接到 SPIFFE_ENDPOINT_SOCKET 处的 SPIRE Agent 套接字。
jwt_source = JwtSource()


def fetch_jwt_svid() -> str:
    svid = jwt_source.fetch_svid(audience={AUDIENCE})
    return svid.token


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=fetch_jwt_svid,
        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, Claude"}],
)
print(message.content[0].text)

验证设置

在接入 SDK 之前，直接从 SPIRE Agent 获取 JWT-SVID 并确认声明与你的联合规则期望的匹配。如果你使用不同的 SPIFFE 实现，请使用其 CLI 或 Workload API 客户端获取 JWT-SVID，并以相同方式解码载荷。

spire-agent api fetch jwt \
    -audience https://api.anthropic.com \
    -socketPath /run/spire/sockets/agent.sock \
    -output json \
  | jq -r '.[0].svids[0].svid' \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

-output json 标志将 SVID 响应和捆绑包响应作为两元素 JSON 数组返回，因此 jq -r '.[0].svids[0].svid' 提取裸令牌。在没有 -output 的旧版 SPIRE 上，命令打印带标签的块；在这种情况下，通过 awk '/^[[:space:]]*eyJ/{print $1; exit}' 管道默认输出以提取令牌行。检查 iss 是否为你注册的 OIDC Discovery Provider URL，sub 是否为工作负载的 SPIFFE ID，aud 是否包含 https://api.anthropic.com。然后运行获取并使用令牌中的 cURL 示例；成功交换会返回一个以 sk-ant-oat01- 开头的 access_token。如果出现 400 invalid_grant，请参阅排查交换失败；最常见的 SPIRE 侧原因是 SPIRE Server 的 jwt_issuer 与注册为联合签发方的 URL 不匹配。

限定规则范围

SPIFFE ID 路径约定由运维人员定义，因此联合规则的 subject_prefix 匹配器应反映你的注册条目使用的路径方案。常见方案包括 spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>（spire-controller-manager 中 ClusterSPIFFEID 资源发出的默认值）和 spiffe://<trust-domain>/host/<hostname>/<service>（用于 VM 和裸金属工作负载）。

将规则的 match 块锁定到适合你用例的最窄范围：

• 固定到一个工作负载： 将 subject_prefix 设置为完整的 SPIFFE ID，不带末尾的 *。
• 始终设置受众： 在规则上要求 audience，并配置 spiffe-helper（或 Workload API 调用）使用相同的值，这样为其他依赖方铸造的 SVID 会被拒绝。
• 按路径段限定范围： 使用 spiffe://prod.example.com/ns/inference/* 授予命名空间下注册的每个工作负载访问权限，并为每个命名空间创建单独的规则和 Anthropic 服务账号，而不是放宽一个规则。
• 每个信任域一个签发方： 每个 SPIRE 信任域都有自己的签名密钥和 OIDC Discovery Provider。将每个注册为单独的联合签发方，并将规则绑定到拥有它们匹配的 SPIFFE ID 的签发方。

后续步骤

• Workload Identity Federation：概念、令牌交换流程和 SDK 配置选项。
• WIF 参考文档：环境变量、JWKS 源模式和规则匹配模式。
• 在 Kubernetes 中使用 WIF：适用于使用原生投影服务账号令牌而非 SPIRE 的集群。