OpenAI 工作负载身份联合

工作负载身份联合（Workload Identity Federation，WIF）让可信工作负载使用已有身份，而不保存长期 OpenAI API 密钥或 ChatGPT 凭证。工作负载提交身份提供商的短期令牌，OpenAI 将其换为短期访问令牌。API 工作负载还可通过 X.509 联合交换已验证的证书身份。

两种方式信任模型相同，管理与运行配置不同。API 路径见使用 API 工作负载身份，Codex 路径见使用 Codex 工作负载身份；规则与生命周期见联合规则参考。

工作原理

管理员预先配置三项：身份提供商说明可信签发者及如何验证令牌/证书；访问规则说明接受哪些属性、可代表哪个 OpenAI 身份（API 称服务账户映射，Codex 称联合规则）；目标主体获得访问（API 为 Platform 服务账户，Codex 为受管理工作区用户/服务账户）。

运行时，工作负载取得短期 OIDC JWT、SPIFFE JWT-SVID，或 API 工作负载提交 X.509 证书；连同产品要求的 ID 呈交外部身份；OpenAI 验证身份并评估映射或规则，随后为映射主体签发短期令牌。交换不会创建主体、项目或工作区成员关系，这些须事先创建或选择。

获取身份令牌

按运行环境选择：

• X.509：API 证书交换。
• Kubernetes：自管理集群的投射服务账户令牌。
• AWS：出站联合或 EKS 投射令牌。
• Microsoft Azure：托管身份或 AKS 投射令牌。
• Google Cloud：元数据服务器身份令牌或 GKE 投射令牌。
• OCI：Oracle 身份域中的实例主体令牌。
• GitHub Actions：CI 的 OIDC 令牌。
• SPIFFE：SPIRE 或兼容提供商的 JWT-SVID。
• Idira：Secure Workload Access 的 JWT-SVID。

支持文档所列配置中的 OIDC 兼容 JWT，包括 SPIFFE JWT-SVID。API 提供商未列出时联系支持；Codex 在 Admin Portal 中选 Custom OIDC。Codex 用户仅执行各指南的令牌签发步骤，再返回本页 Codex 小节；各提供商的 OpenAI 配置与 SDK 示例属于 API 路径。X.509 仅支持 API 路径。

在 OpenAI API 中使用工作负载身份

需要组织内管理提供商和服务账户映射的权限。到组织设置 > Security > Workload Identity Provider先创建提供商，再在详情页配置映射。

X.509 提供商

它从证书派生身份属性，复用组织现有 mTLS 验证，不另存证书或独立信任库。先在组织 mTLS 设置配置并激活客户端证书所链到的信任锚。权限、证书、作用域、主机、链验证、CEL 和轮换见 mTLS 指南。

创建提供商，派生一个非空 openai.subject，映射至最小权限项目服务账户。工作负载向 X.509 端点提交证书换取令牌，再向 API mTLS 主机同时发送 bearer 与被接受的证书；完整流程见 X.509 指南。

配置 OIDC 工作负载身份提供商

每个可信外部签发者创建一个提供商，支持 OIDC JWT 主体令牌。配置项如下：

自定义 OIDC 发现和上传 JWKS 互斥；启用前者会隐藏后者。自定义发现 URL 必须为公开 HTTPS，不含凭证、自定义端口、查询或片段。界面没有该选项时用标准发现，或上传提供商公开 JWKS，并随签名密钥轮换更新。

签发者与发现主机不同，OIDC Issuer URL 仍设为令牌 iss，Custom OIDC discovery URL 指向发布发现文档的位置；自定义 URL 只改变发现元数据/公钥的获取位置，不改变签发者验证。

使用 CEL 转换令牌声明

属性转换采用 CEL 标准语法，不增加 WIF 自定义函数。表达式根对象 assertion 是已验证 JWT 声明集合。控制台自动加 openai. 前缀；输入后缀 subject、表达式 assertion.sub，存为 openai.subject。

来源示例 1（json）：

中文说明：来源配置或结果示例，按所在小节的字段、作用域与权限要求解释；JSON保持合法格式，CEL/声明匹配文本不是可独立运行的应用。

[
  {
    "attribute": "openai.subject",
    "expression": "assertion.sub"
  },
  {
    "attribute": "openai.repository",
    "expression": "assertion.repository"
  }
]

可读取 assertion.sub、assertion.repository 等，不支持的语法/函数会导致映射失败：

来源示例 2（json）：

中文说明：来源配置或结果示例，按所在小节的字段、作用域与权限要求解释；JSON保持合法格式，CEL/声明匹配文本不是可独立运行的应用。

[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  },
  {
    "attribute": "openai.production",
    "expression": "assertion.ref == \"refs/heads/main\""
  }
]

结果必须为字符串、布尔值、整数或有限数；数组、对象、null 和求值错误均失败。比较前将标量转为字符串，例如 true 变为 "true"，7 变为 "7"。以 openai. 开头的映射键只从转换读取；令牌原始同名前缀声明不会自动参与匹配。

管理 JWKS 与密钥轮换

标准发现先获取 /.well-known/openid-configuration，再获取 jwks_uri，发现文档与远程 JWKS 缓存 600 秒。自定义发现从指定基址获取文档，但 iss 仍须匹配配置。缓存找不到 kid 时，会刷新 JWKS 并再查一次。

上传 JWKS 模式不执行发现或远程获取；提供商更新对交换生效后，使用保存的 JWKS。可有多个公钥，但各 kid 必须唯一且非空。

轮换期间同时公布新旧公钥，让旧令牌继续工作。上传模式须在签发新 kid 令牌前更新配置，不存在于配置的密钥签名会被拒绝。

配置服务账户映射

映射规定哪些外部身份能为指定服务账户取得令牌。X.509 只用派生 openai.* 属性，优先精确 openai.subject；原始 sub、aud、iss 仅适用于 OIDC。

属性值须为 JSON 标量。字符串允许非空前缀后一个末尾通配符，如 repo:openai/*、repository:my-org/*；不支持 *、repo:*:prod、repo/*/main。界面 Permissions 对应交换响应 OAuth scope，只能收窄服务账户权限，不可包含 Admin API scopes，下游授权仍适用。

映射解析示例

外部身份验证后，仅查找请求 identity_provider_id 和 service_account_id 的映射，跳过未启用项，按每个映射所需属性求值；只有恰好一个启用映射满足全部属性时才签发。

假设 GitHub 令牌声明如下：

来源示例 3（json）：

中文说明：来源配置或结果示例，按所在小节的字段、作用域与权限要求解释；JSON保持合法格式，CEL/声明匹配文本不是可独立运行的应用。

{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "repository": "my-org/my-repo",
  "ref": "refs/heads/main"
}

派生属性：

来源示例 4（json）：

中文说明：来源配置或结果示例，按所在小节的字段、作用域与权限要求解释；JSON保持合法格式，CEL/声明匹配文本不是可独立运行的应用。

[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  }
]

映射同时要求原始与派生属性：

三行必须全匹配。sub 末尾通配符匹配 repo:my-org/my-repo: 前缀；openai.repository_ref 从转换而非原始同名声明读取。多个映射匹配会拒绝；每个提供商/服务账户组合须唯一，不合并映射权限。

连接工作负载

使用对应提供商的 SDK 示例或直接交换端点。字段、授权及限制见交换接口参考。

续期访问令牌

自行管理交换时，应一同传递 access_token 和 expires_at。后者是秒级 Unix UTC 绝对到期时间，须提前续期并留出时钟、网络余量。expires_in 从签发时计时；12:00 签发、3600 秒有效，即使12:05才收到也仍于13:00到期，传输不会延长寿命。参见响应字段。不返回刷新令牌，续期要用有效外部令牌或证书重新交换。

在 Codex 中使用工作负载身份

用于受管理 ChatGPT 工作区的可信自动化，将工作负载映射到 ChatGPT 用户或服务账户，而非 API Platform 服务账户。此能力处于 beta，须为工作区开通；请联系 OpenAI 代表或支持。规则参考说明一条规则如何接受多个外部主体并映射到一个 ChatGPT 主体。

连接故障排查

OpenAI 拒绝身份令牌

本地解码并对照 iss、aud、sub、exp、iat 及提供商特有声明，不向第三方 JWT 网站粘贴生产令牌。API 比较服务账户映射，Codex 比较联合规则。

API 映射不匹配

确认使用正确提供商和服务账户 ID、映射活动且恰好匹配一条。详见交换错误参考。

Codex 提示配置不完整

确认进程具有两个必需的工作负载身份环境变量，OPENAI_IDENTITY_TOKEN_FILE 是当前令牌的绝对路径，检查文件及父目录权限。

Codex 使用了其他凭证

两个必需变量都应加载。任一变量出现就会优先选择 WIF，而不是 API 密钥、访问令牌或已保存登录。加载下载的配置后启动新进程，再运行 codex login status。

安全建议

每应用/工作负载专用主体，隔离生产与非生产；优先精确声明匹配而非宽泛模式；最小权限与短期令牌；定期清理闲置提供商、映射、规则，检查交换错误与异常访问。

相关文档

• Codex 联合规则
• 令牌交换参考
• Codex 认证
• Codex 环境变量
• Codex 非交互模式