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

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

使用 Idira Secure Workload Access(SWA)调用 OpenAI API,无需存储 OpenAI API 密钥。SWA 会为您的工作负载分配一个 SPIFFE ID,并签发一个代表该身份的签名令牌 JWT-SVID。OpenAI SDK 使用该令牌换取短期有效的 OpenAI 访问令牌,其权限来自映射的服务账号。

本指南介绍 OpenAI API 的配置方法。如果您使用 Codex,请先按本文的步骤向工作负载提供令牌,再按照在 Codex 中使用工作负载身份中的说明操作。

开始之前

您需要满足以下条件:

  • 已部署 SWA,并配置了信任域和证明策略,该策略会为您的工作负载分配预期的 SPIFFE ID。
  • 工作负载可以访问 SWA Agent 的 Workload API 套接字。
  • 您有权管理 OpenAI 组织中的工作负载身份提供方、服务账号映射、项目和服务账号。
  • 您使用的 OpenAI SDK 支持工作负载身份凭据。

请根据 Idira 的 OpenAI 集成指南中列出的前提条件,完成 SWA 基础设施配置。

获取签发方和签名密钥

获取信任域的 jwt.discovery_endpoints.oidc_discovery_url 和 jwt.discovery_endpoints.jwks_uri。您可以按照 Idira 的 OIDC 配置说明查找这两个值。

OpenAI 必须能够通过 HTTPS 访问发现文档和 JWKS,且无需提供凭据。签发方由令牌的 iss 声明中的 HTTPS URL 指定。sub 中的 SPIFFE ID 用于标识您的工作负载。

为访问 OpenAI 选择一个专用的受众值,例如 https://api.openai.com/v1。请求 JWT-SVID 和配置 OpenAI 身份提供方时,请使用相同的值。受众值用于标识令牌的预期接收方,并不决定令牌交换端点。

SWA 默认使用 RS512 算法和 4096 位 RSA 密钥进行签名。OpenAI 的 JWT 验证器支持这一组合。有关 SWA 的其他签名选项,请参阅 Idira 的 JWT 要求。

为工作负载提供持续刷新的 JWT-SVID

在工作负载环境中安装 spiffe-helper,以便向 SWA Agent 请求 JWT-SVID 并定期刷新。将以下配置保存为 helper.conf。辅助程序会将令牌写入 /var/run/spiffe/openai.jwt,这也是通用 SPIFFE SDK 示例使用的路径:

agent_address = "/tmp/swa-agent/public/api.sock"
cert_dir      = "/var/run/spiffe"
daemon_mode   = true

jwt_svids = [{
  jwt_audience       = "https://api.openai.com/v1"
  jwt_svid_file_name = "openai.jwt"
}]

在 Kubernetes 中,请在工作负载的 Pod 中以边车容器运行辅助程序。请让工作负载和边车容器共享一个基于内存的 emptyDir 卷,将该卷挂载到 /var/run/spiffe,并将 SWA 套接字的父目录 /tmp/swa-agent/public 挂载到边车容器中。在虚拟机上,请使用 /run/swa-agent/api.sock 作为 agent_address 的值,并将令牌目录放在基于内存的存储上。请按照 Idira 的部署说明配置套接字访问和工作负载证明。

启动辅助程序前,请先创建令牌目录,并授予辅助程序写入权限。在边车容器或虚拟机服务中,使用上述配置启动辅助程序:

spiffe-helper -config helper.conf

仅允许确实需要令牌文件或代理套接字的进程访问相应资源。请保持辅助程序运行,以便它在令牌过期前将其替换。

如果您使用的编程语言有 SPIFFE Workload API 客户端,也可以在主体令牌提供方中获取新的 JWT-SVID。请参阅 Idira 的集成指南中直接调用 Workload API 的方法。

检查令牌

在工作负载内,将令牌读入本地解码器使用的环境变量:

export TOKEN="$(cat /var/run/spiffe/openai.jwt)"
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]));

创建 OpenAI 身份提供方前,请检查以下字段:

字段 预期值
标头中的 alg 配置的签名算法,例如 RS512。
标头中的 kid 信任域的公开 JWKS 中某个签名密钥的 ID。
iss 信任域的 HTTPS 签发方 URL。
sub 分配给此工作负载的 SPIFFE ID。
aud 包含您为访问 OpenAI 选择的受众值。
iat 和 exp 分别为令牌的签发时间和过期时间。请使用尚未过期的令牌。

解码器只读取声明,不验证签名。请勿将令牌写入日志或粘贴到在线解码器中。检查完毕后,请取消设置 TOKEN 环境变量。

配置 OpenAI 工作负载身份联合

创建工作负载身份提供方

前往组织设置 > 安全 > 工作负载身份提供方,使用以下设置创建身份提供方:

设置 值
名称 唯一的名称,例如 idira-prod。
描述 使用此身份提供方的应用和环境。
OIDC 签发方 URL JWT-SVID 的 iss 值。
受众 辅助程序请求令牌时指定的受众值,例如 https://api.openai.com/v1。
使用上传的 JWKS 验证令牌 保持此选项关闭,以使用 OIDC 发现机制。
属性转换 直接从 sub 建立映射时,请留空。

在 OpenAI API 令牌交换过程中,比较签发方 URL 时会忽略末尾的斜杠。例如,https://issuer.example.com 和 https://issuer.example.com/ 视为匹配。其余字符必须完全一致,包括协议和路径。受众值必须完全匹配。请原样复制令牌中的签发方 URL,以保持配置一致。

如果 OpenAI 无法访问发现文档或 JWKS,请按照身份提供方通用配置指南中的说明上传公开 JWKS。SWA 轮换签名密钥时,请更新已上传的密钥。

将 SPIFFE ID 映射到服务账号

  1. 在身份提供方中创建服务账号映射,并为其命名,例如 idira-production-workload。
  2. 将键设为 sub,将值设为与工作负载令牌中完全一致的 SPIFFE ID,例如 spiffe://prod.example.com/k8s-nodegroup/ns/my-namespace/sa/my-service-account。
  3. 选择工作负载可以使用的项目和服务账号。
  4. 选择工作负载所需的权限,例如为模型请求选择 api.model.request。这些权限只能缩小服务账号的访问范围,不能授予超出该范围的权限。将权限留空时,工作负载身份联合不会施加额外限制。

请为每个应用在每个环境中分别设置服务账号。优先使用完整的 SPIFFE ID 进行精确匹配。仅当具有同一前缀的所有身份都应获得相同的访问权限时,才在末尾使用通配符。避免映射范围重叠。详情请参阅 SPIFFE 服务账号映射。

在代码中使用令牌

在工作负载的环境变量中设置 OpenAI 身份提供方的 ID 和所选服务账号的 ID:

export OPENAI_IDENTITY_PROVIDER_ID="<workload identity provider ID>"
export OPENAI_SERVICE_ACCOUNT_ID="<service account ID>"

以下通用 SPIFFE 示例从 /var/run/spiffe/openai.jwt 读取令牌。每当 SDK 需要换取或刷新 OpenAI 访问令牌时,主体令牌提供方都会返回当前的 JWT-SVID。SWA 和辅助程序负责刷新外部 JWT-SVID,OpenAI SDK 负责管理 OpenAI 访问令牌。

使用 Idira 签发的 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);

验证配置和排查问题

确保 OPENAI_API_KEY 未设置,然后在已通过证明的工作负载中运行示例。请求成功时,示例会输出模型的回复。请确认辅助程序替换 JWT-SVID 且 SDK 刷新 OpenAI 访问令牌后,请求仍能成功。

现象 检查方法
辅助程序未获得身份 检查工作负载是否符合 SWA 证明策略,以及能否访问代理套接字。请在工作负载的运行环境中执行检查。
令牌文件缺失、内容为空或其中的令牌已过期 检查辅助程序是否正在运行、共享卷与文件路径是否对应,以及工作负载能否读取该文件。请保持各主机的时钟同步。
令牌验证失败 检查 iss、aud、kid 和令牌过期时间,并确认发现文档和 JWKS 均可访问。请按上文所述规则比较签发方 URL。
没有匹配的服务账号映射 核对身份提供方 ID 和服务账号 ID,确认映射已启用,并检查 sub 值是否完全匹配。
有多个映射匹配 缩小重叠映射的范围或停用部分映射,确保只有一个已启用的映射匹配。
令牌交换成功,但 API 拒绝请求 检查映射的服务账号所属的项目、该账号的权限以及适用的 API 访问策略。

有关 SWA 部署问题的诊断方法,请参阅 Idira 的集成故障排查指南。