如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

为 SPIFFE 配置工作负载身份联合

您可以将 SPIFFE 用作工作负载身份提供方,用 SPIFFE JWT-SVID 换取短期 OpenAI 访问令牌。这样,通过 SPIRE 或其他兼容 SPIFFE 的身份提供方认证的工作负载就能调用 OpenAI API,无需存储长期有效的 API 密钥。

如果您使用 Idira Secure Workload Access,请按照 Idira 设置指南配置代理程序和令牌交付方式。

OpenAI 支持将 SPIFFE JWT-SVID 作为 JWT 主体令牌进行验证。这类令牌必须包含签发方、受众、过期时间和签发时间戳,并带有可通过 JWKS 验证的签名。OpenAI 不支持将 SPIFFE X.509-SVID 用作工作负载身份联合的主体令牌。

JWT-SVID 规范要求令牌包含 sub、aud 和 exp 声明。要在 OpenAI 中使用 JWT-SVID,令牌还必须包含 iss 和 iat 声明,并在标头中包含 kid 字段,以便 OpenAI 根据工作负载身份提供方的配置验证令牌。

JWT-SVID 不是 OpenID Connect ID 令牌。SPIRE OIDC Discovery Provider 提供发现元数据和 JWKS 密钥,供 OpenAI 验证 JWT-SVID。它不会改变令牌的 SPIFFE 语义,也不要求使用 OIDC 登录流程。

有关 SPIFFE 术语和令牌要求,请参阅 SPIFFE 的 JWT-SVID 规范和 Workload API 规范。

设置 SPIFFE

配置 SPIFFE 提供方,使其为需要调用 OpenAI API 的工作负载签发 JWT-SVID。以下说明使用 SPIRE 术语。对于其他兼容 SPIFFE 的提供方,只要其签发的 JWT-SVID 包含 OpenAI 可验证的签发方信息,且提供可供 OpenAI 验证签名的 JWKS 密钥,OpenAI 端的配置方式就相同。

您的 SPIFFE 配置必须提供以下内容:

  • 工作负载的稳定 SPIFFE ID,例如 spiffe://example.org/ns/production/sa/openai-wif。
  • 一个专用于访问 OpenAI 的 JWT-SVID 受众,例如 https://api.openai.com/v1,也可以是您自行选择的其他不透明标识符。
  • JWT 签发方 URL。该 URL 必须出现在 JWT-SVID 的 iss 声明中,供 OpenAI 验证。
  • 包含 JWT-SVID 签名密钥对应公钥的 JWKS,可通过 OIDC 发现机制提供,也可上传。
  • 工作负载从 SPIFFE Workload API 获取新 JWT-SVID 的方式。

受众是一个必须精确匹配的标识符,不一定是接收 JWT-SVID 的端点。您可以使用 https://api.openai.com/v1 或其他服务专用值,只要 SPIFFE Workload API 请求中的受众与 OpenAI 提供方配置中的受众一致即可。

条件允许时,请通过 SPIRE OIDC Discovery Provider 发布 SPIFFE 签发方信息。将 SPIRE Server 的 jwt_issuer 和 OIDC Discovery Provider 的 jwt_issuer 设为同一个 HTTPS 签发方 URL,并在 OpenAI 中配置相同的 URL。

在 SPIRE Server 配置中:

server {
  trust_domain = "example.org"
  jwt_issuer   = "https://spire-oidc.example.org"
}

在单独的 SPIRE OIDC Discovery Provider 配置中:

# Relevant issuer fields only
domains    = ["spire-oidc.example.org"]
jwt_issuer = "https://spire-oidc.example.org"

配置 OIDC Discovery Provider 时,还需要指定密钥材料来源,例如 server_api、workload_api 或 file,以及提供服务的方式,例如 ACME、TLS 证书或 Unix 套接字。完整的配置选项请参阅 SPIRE OIDC Discovery Provider 文档。

SPIFFE 信任域与 JWT 签发方是两个不同的概念。在本例中,JWT-SVID 的主体是 example.org 信任域中的一个 SPIFFE ID,而签发方由 HTTPS 签发方 URL 标识:

{
  "sub": "spiffe://example.org/ns/production/sa/openai-wif",
  "iss": "https://spire-oidc.example.org"
}

SPIRE OIDC Discovery Provider 提供 OIDC 发现文档和 JWKS 端点。关闭使用上传的 JWKS 验证令牌时,OpenAI 可以使用该文档和端点。

如果 OpenAI 无法访问您的签发方发现端点,请改用上传 JWKS 的模式。在此模式下,OpenAI 仍会检查工作负载身份提供方配置中的签发方是否与 JWT-SVID 的 iss 声明一致,但会使用您在工作负载身份提供方配置中保存的 JWKS JSON 验证签名。

注意: SPIFFE JWT-SVID 规范将 JWT 标头中的 kid 字段列为可选字段,但 OpenAI 要求 JWT 主体令牌的标头包含 kid,以便从配置的 JWKS 中选择签名密钥。如果您的 SPIFFE 提供方可能省略 kid,请将其配置为在用于 OpenAI 工作负载身份联合的令牌中包含该字段。

要在能够调用 SPIFFE Workload API 的工作负载中检查 JWT-SVID,请使用您将在 OpenAI 中配置的受众请求令牌。请在应用程序所在的工作负载上下文中运行以下命令,因为 Workload API 根据调用进程的身份进行授权。

TOKEN=$(spire-agent api fetch jwt \
  -socketPath /run/spire/sockets/agent.sock \
  -audience "https://api.openai.com/v1" | sed -n '2p')
export TOKEN

如果您的工作负载有多个 SPIFFE ID,请在请求中指定所需的身份:

TOKEN=$(spire-agent api fetch jwt \
  -socketPath /run/spire/sockets/agent.sock \
  -spiffeID "spiffe://example.org/ns/production/sa/openai-wif" \
  -audience "https://api.openai.com/v1" | sed -n '2p')
export TOKEN

验证令牌

在配置工作负载身份联合之前,请将 JWT-SVID 导出为环境变量 TOKEN,然后在本地运行以下任一示例,检查令牌的标头和声明:

const parts = process.env.TOKEN?.split(".") ?? [];
if (parts.length !== 3) {
  throw new Error("Expected a compact JWT with three segments");
}

const decode = (segment: string) => {
  if (!/^[A-Za-z0-9_-]+$/.test(segment) || segment.length % 4 === 1) {
    throw new Error("JWT segment is not valid Base64URL");
  }
  const bytes = Buffer.from(segment, "base64url");
  if (bytes.toString("base64url") !== segment) {
    throw new Error("JWT segment is not valid Base64URL");
  }
  const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
  const value = JSON.parse(decoded);
  if (value === null || Array.isArray(value) || typeof value !== "object") {
    throw new Error("JWT segment is not a JSON object");
  }
  return decoded;
};

console.log("Header:");
console.log(decode(parts[0]));
console.log("\nPayload:");
console.log(decode(parts[1]));

这些示例只解码 JWT,不验证令牌签名。请使用本地解码器处理生产环境的令牌,避免将其粘贴到第三方工具中。

解码后的 SPIFFE JWT-SVID 类似于以下示例:

{
  "alg": "ES256",
  "kid": "jwt-svid-key-1"
}
{
  "iss": "https://spire-oidc.example.org",
  "aud": ["https://api.openai.com/v1"],
  "sub": "spiffe://example.org/ns/production/sa/openai-wif",
  "iat": 1716235422,
  "exp": 1716235722
}

在交换令牌之前,请将收到的令牌解码,并与 OpenAI 配置进行核对。检查标头中的 alg 和 kid,以及载荷中的 iss、aud、sub、iat 和 exp。alg 的具体值取决于 SPIRE Server 的 JWT 签名密钥配置。

设置工作负载身份联合

在 OpenAI 中为 SPIFFE JWT-SVID 签发方创建工作负载身份提供方,然后添加与您信任的 SPIFFE ID 匹配的服务账号映射。

设置工作负载身份提供方

  1. 创建工作负载身份提供方。 将名称设为唯一值,例如 spiffe-prod。填写描述,例如 Production SPIFFE workloads,以便管理员识别该提供方。

  2. 设置签发方和受众。 将 OIDC 签发方 URL 设为与 JWT-SVID 的 iss 声明完全一致的值,例如 https://spire-oidc.example.org。将受众设为向 SPIFFE Workload API 请求令牌时指定的受众值。本例中使用 https://api.openai.com/v1。

  3. 选择 JWKS 来源。 如果 OpenAI 可以访问您的 SPIRE OIDC Discovery Provider,请保持使用上传的 JWKS 验证令牌选项关闭。OpenAI 会通过 OIDC 发现机制获取 JWKS,并用它验证 JWT-SVID 签名。

    如果 OpenAI 无法访问签发方,请启用使用上传的 JWKS 验证令牌,然后将 JWKS JSON 设为 JWT-SVID 签名密钥对应的公钥集。请上传完整的公开 JWKS 对象,包括容纳各公钥条目的 keys 数组。请勿包含私钥材料。

  4. 仅在需要派生映射属性时添加属性转换。 如果直接使用 sub 进行映射,则无需转换属性。只有在需要从一个或多个令牌声明派生映射值时,才使用属性转换。有关转换机制,请参阅工作负载身份联合主指南。

设置服务账号映射

  1. 创建服务账号映射。 将名称设为在该工作负载身份提供方内唯一的值,例如 production-openai-wif。填写描述,例如 Production SPIFFE workload for OpenAI API access,说明哪个工作负载可以使用该映射。

  2. 匹配 SPIFFE ID。 将键设为 sub,将值设为工作负载的 SPIFFE ID,例如 spiffe://example.org/ns/production/sa/openai-wif。

    对于具有高权限的工作负载,请优先使用精确匹配的 SPIFFE ID。只有在该前缀下的每个 SPIFFE ID 都应能获取 OpenAI 访问令牌时,才在末尾使用通配符。例如,spiffe://example.org/ns/production/sa/* 允许任何路径与之匹配的生产环境服务账号获取令牌。

  3. 选择目标 OpenAI 服务账号。 将项目设为目标服务账号所属的 OpenAI 项目。将服务账号设为 SPIFFE 工作负载可以使用的 OpenAI 服务账号,例如 spiffe-prod-openai-wif。如果您希望为此映射创建新的服务账号,而不复用现有账号,请勾选 Create a new service account in this project。

  4. 按需缩小 API 权限范围。 选择适当的权限,例如 api.model.request 和 api.vector_store.read,以进一步限制通过此映射签发的访问令牌的权限。如果您无需针对工作负载身份联合额外限制权限范围,请将权限留空。令牌仍以映射到的服务账号身份获得授权。

在代码中使用令牌

配置 OpenAI SDK 客户端,使其用新获取的 SPIFFE JWT-SVID 换取 OpenAI 签发的访问令牌。

以下 SDK 示例假设您的 SPIFFE 集成会刷新 JWT-SVID 并将其写入 /var/run/spiffe/openai.jwt。请将文件权限设置为仅允许该工作负载读取。由于 JWT-SVID 的有效期很短,请在令牌过期前更新文件。如果条件允许,您也可以在主体令牌提供方中使用所用编程语言的 SPIFFE 库,直接从 SPIFFE Workload API 获取 JWT-SVID,以免读到文件中的过期令牌。

在工作负载环境中设置 OPENAI_IDENTITY_PROVIDER_ID 和 OPENAI_SERVICE_ACCOUNT_ID。令牌文件包含外部主体令牌。OPENAI_IDENTITY_PROVIDER_ID 标识 OpenAI 工作负载身份提供方,OPENAI_SERVICE_ACCOUNT_ID 标识目标 OpenAI 服务账号。随后,OpenAI 会根据令牌声明查找与该提供方和服务账号匹配的映射。

使用 SPIFFE JWT-SVID 进行身份验证
import { readFile } from "node:fs/promises";
import OpenAI from "openai";

const tokenPath = "/var/run/spiffe/openai.jwt";
const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;

if (!identityProviderId || !serviceAccountId) {
  throw new Error(
    "Set OPENAI_IDENTITY_PROVIDER_ID and OPENAI_SERVICE_ACCOUNT_ID"
  );
}

function spiffeJwtSvidProvider(path: string) {
  return {
    tokenType: "jwt" as const,
    getToken: async () => {
      const token = (await readFile(path, "utf8")).trim();
      if (!token) {
        throw new Error("The SPIFFE JWT-SVID file is empty.");
      }
      return token;
    },
  };
}

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId,
    serviceAccountId,
    provider: spiffeJwtSvidProvider(tokenPath),
  },
});

const response = await client.responses.create({
  model: "gpt-6.1-terra",
  input: "Say hello from SPIFFE workload identity federation.",
});

console.log(response.output_text);

SPIFFE 最佳实践

  • 使用 JWT-SVID 进行 OpenAI 工作负载身份联合。X.509-SVID 可用于双向 TLS 认证,但 OpenAI 令牌交换端点不接受 X.509-SVID。
  • 为访问 OpenAI 指定单一的专用受众。避免使用范围过大的受众,例如整个信任域或环境名称。
  • 尽可能精确匹配 SPIFFE ID。仅在明确需要共享信任边界时使用通配符映射。
  • 为 JWT-SVID 设置较短的有效期,以降低持有者令牌遭受重放攻击的风险。OpenAI 访问令牌的过期时间不会晚于交换时使用的外部主体令牌。
  • 谨慎轮换签名密钥。在轮换期间通过 OIDC 发现机制同时发布新旧公钥,或在使用新的 kid 签发 JWT-SVID 之前更新已上传的公开 JWKS。
  • 保持 SPIRE Server 与工作负载的时钟同步。时钟偏差过大时,原本有效的 JWT-SVID 可能因被判定为尚未生效、签发时间过早或已过期而遭到拒绝。
  • 保护 SPIFFE Workload API 套接字。能够获取工作负载 JWT-SVID 的进程可以尝试用它换取 OpenAI 访问令牌。
  • 确保 OpenAI 服务账号的权限边界与应用程序和环境的权限边界一致。不要让不相关的 SPIFFE 工作负载共用高权限服务账号。
  • 监控令牌交换失败的情况,检查签发方、受众、签名密钥或映射是否匹配。