工作负载身份联合

工作负载身份联合让受信任的工作负载使用已有身份，无需存储 OpenAI API 密钥或 ChatGPT 凭据。工作负载提供由您的身份提供商签发的短期 Token，OpenAI 将其交换为短期 OpenAI 访问 Token。

OpenAI API 工作负载还可以通过 X.509 工作负载身份联合，使用经过验证的证书身份进行交换。

您可以在 OpenAI API 或 Codex 中使用工作负载身份联合：

两种方式使用相同的信任模型，但管理方式和运行时配置不同。请先阅读下方的通用概念和身份提供商指南，再按照您的工作负载所使用产品的相应章节操作。

• OpenAI API： 继续阅读在 OpenAI API 中 使用工作负载身份。
• Codex： 请按照在 Codex 中 使用工作负载身份完成管理门户和 运行时的全部设置。

管理员还可以使用管理 API 管理 Codex 提供商和规则。有关 规则和生命周期行为，请参阅Codex 联合规则 参考资料。

工作原理

在工作负载连接之前，管理员需要配置以下三项：

1. 身份提供商 告知 OpenAI 应信任哪个外部签发者，以及 如何验证其签名 Token 或证书身份。
2. 访问规则 说明 OpenAI 接受哪些 Token 属性，以及 工作负载可以使用哪个 OpenAI 身份执行操作。在 OpenAI API 配置中，这称为 服务账户映射；在 Codex 配置中，则称为联合规则。
3. OpenAI 主体 获得最终的访问权限。对于 OpenAI API， 主体是平台服务账户。对于 Codex，主体是 受管理的工作空间中的 ChatGPT 用户或服务账户。

运行时的流程如下：

1. 工作负载接收短期 OIDC JWT 或 SPIFFE JWT-SVID；如果是 OpenAI API 工作负载，也可以提供 X.509 证书。
2. 工作负载提供其外部身份以及所用产品要求的 ID。
3. OpenAI 验证 Token 或证书，然后评估已配置的映射或规则。
4. OpenAI 为映射到的主体返回短期访问 Token。

Token 交换不会创建主体、项目或工作空间成员关系。管理员需在设置时创建或选择这些资源。

获取身份 Token

请根据您的工作负载运行的环境选择指南：

在文档所述的配置中，OpenAI 支持 兼容 OIDC 的 JWT 主体 Token，包括 SPIFFE JWT-SVID。对于 OpenAI API，如果未列出您的 OIDC 提供商，请联系 OpenAI 支持团队。对于 Codex，请在 OpenAI 管理门户中选择 自定义 OIDC 。

每份 OIDC 提供商指南都说明了如何签发和检查 Token。对于 Codex， 请仅执行其中的 Token 签发步骤，然后返回 在 Codex 中使用工作负载身份。 这些指南中的 OpenAI 设置和 SDK 示例适用于 OpenAI API 方式。X.509 联合仅支持 OpenAI API 方式。

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

如果您的工作负载直接调用 OpenAI API，请使用此方式。您需要具备管理组织的工作负载身份提供商和服务账户映射的权限。

前往组织设置 > 安全 > 工作负载身份提供商。 先创建提供商，再从 提供商详情页配置其服务账户映射。

X.509 提供商

X.509 提供商从客户端证书中派生工作负载身份属性，OpenAI 则根据您组织现有的双向 TLS 配置验证该证书。提供商不存储证书，也不维护单独的信任存储。

创建提供商之前，请配置并激活作为客户端证书信任锚的受信任证书， 设置位置为组织设置 > 安全 > 双向 TLS。 双向 TLS 指南介绍了权限、 证书要求、激活范围、mTLS 主机、证书链行为、 CEL 过滤器和轮换。

接下来，创建 X.509 提供商，派生一个非空的 openai.subject 值，并将该身份映射到仅具有工作负载所需权限的项目服务账户。工作负载向 X.509 Token 端点提供其证书以获取短期持有者 Token，然后将该持有者 Token 和一个被接受的客户端证书发送到 API mTLS 端点。

请按照X.509 证书设置指南完成控制台操作和请求的完整流程。

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

为您信任的每个外部签发方创建一个工作负载身份提供商。OpenAI API 工作负载身份支持 OIDC JWT 主体 Token。其配置包括：

自定义 OIDC 发现与上传的 JWKS 互斥。启用自定义发现后，上传 JWKS 的选项会被隐藏。自定义发现 URL 必须使用公共 HTTPS，且不能包含凭据、自定义端口、查询字符串或片段。

如果您的控制台中未显示 使用自定义 URL 进行 OIDC 发现 ，请使用 标准 OIDC 发现，或启用 使用上传的 JWKS 验证 Token 。请使用身份提供商发布的公钥 JWKS，并在提供商轮换签名密钥时 更新该 JWKS。

当 Token 签发方与发现主机不同时，请将 OIDC 签发方 URL 设为 Token 的 iss 声明值，并将 自定义 OIDC 发现 URL 设为发布 提供商发现文档的主机地址。OpenAI 仍会根据 配置的签发方检查 Token；自定义 URL 仅决定获取发现 元数据和签名公钥的位置。

使用 CEL 转换 Token 声明

属性转换使用通用表达式语言（CEL）。OpenAI 支持 langdef.md 中规定的标准 CEL 运算符， 不提供额外的工作负载身份联合自定义函数。每个表达式 接收一个根对象：

• assertion：已验证的 JWT 声明集。

控制台会自动添加 openai. 前缀。请输入 后缀（例如 subject）和表达式（例如 assertion.sub）。API 会将派生属性存储为 openai.subject。

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

请使用 CEL 语言规范定义的 CEL 语法。例如，您可以 使用 assertion.sub 或 assertion.repository 等表达式读取声明值。不受支持的语法或函数会导致 映射解析失败。

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

转换结果必须为标量值：字符串、true 或 false 值、整数或有限数值。数组、对象、空值以及 求值错误都会导致映射解析失败。OpenAI 会先将标量 转换结果转为字符串，再与映射值进行比较。 例如，true 会变为 "true"，7 会变为 "7"。

以 openai. 开头的映射键只能从属性转换结果中 解析。对于本身已使用 openai. 前缀的原始主体 Token 声明， 除非您配置了相应的转换，否则它们不会影响映射判定。

管理 JWKS 和密钥轮换

OpenAI 使用工作负载身份提供商上配置的密钥来源来验证 OIDC 主体 Token：

• OIDC 发现： OpenAI 获取签发方的 /.well-known/openid-configuration，然后从发现的 jwks_uri 获取密钥。 OpenAI 会将发现文档和远程 JWKS 载荷缓存 600 秒。
• 自定义 OIDC 发现： OpenAI 从配置的自定义发现基础 URL 获取 /.well-known/openid-configuration， 然后从发现的 jwks_uri 获取密钥。Token 的 iss 声明 仍必须与 OIDC 签发方 URL 匹配。
• 未命中时刷新密钥： 如果在缓存的 JWKS 中找不到 Token 的 kid， OpenAI 会先刷新 JWKS 并再次尝试查找， 然后才会拒绝该 Token。
• 上传的 JWKS： 启用 使用上传的 JWKS 验证 Token 后， OpenAI 会使用上传并存储在提供商配置中的 JWKS， 不执行 OIDC 发现，也不获取远程 JWKS。提供商配置更新 对 Token 交换生效后，新的交换请求会使用已保存的 JWKS。
• 密钥集： 一个 JWKS 可以包含多个公钥。每个密钥都必须具有 唯一且非空的 kid。

轮换签名密钥时，请在轮换窗口内将新旧公钥同时发布到签发方的 JWKS 中。这样，使用旧密钥签名的 Token 可以继续 使用，同时 OpenAI 也能接受使用新密钥签名的 Token。对于上传的 JWKS， 请先更新提供商配置，再签发带有新 kid 的 Token； 如果签名密钥不在已配置的 JWKS 中，OpenAI 会拒绝相应的 Token。

配置服务账户映射

服务账户映射定义了哪些外部身份可以为 OpenAI 服务账户生成访问令牌。

对于 X.509 提供商，映射键使用派生的 openai.* 属性。建议使用 精确的 openai.subject 映射。sub、aud 和 iss 等原始 JWT 声明 仅适用于 OIDC 提供商。

其配置包括：

属性值必须为 JSON 标量值。字符串值可以在末尾使用一个 通配符，但前缀不能为空，例如 repo:example/*。不支持单独使用通配符 或将通配符放在值的中间。

有效的通配符值：

• repo:openai/*
• repository:my-org/*

不受支持的通配符值：

• *
• repo:*:prod
• repo/*/main

控制台将映射限制显示为 权限。Token 交换 响应在 scope 属性中以 OAuth 作用域的形式 返回相同的限制。映射不能包含管理 API 作用域，且下游 API 的常规 授权规则仍然适用。

映射解析示例

OpenAI 验证外部身份后，开始解析映射。 OpenAI 根据请求中的 identity_provider_id 和 service_account_id 查找映射，跳过未启用的映射，并且只评估 各映射所需的属性。只有恰好一个已启用的映射 与所有配置的属性匹配时，才会签发令牌。

假设一个 GitHub Actions 令牌包含以下声明：

1234567{
  "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"
}

身份提供方可以派生出一个属性：

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

随后，服务账户映射可以同时要求匹配原始属性和派生属性：

这三个值必须全部匹配。sub 的值使用了末尾通配符，因此 可以匹配任何以 repo:my-org/my-repo: 为前缀的值。 openai.repository_ref 键的值通过属性转换解析得到， 而非取自同名的原始令牌声明。

如果一次交换匹配了多个已启用的映射，OpenAI 会拒绝该交换。 OpenAI 要求每个 (provider, service account) 组合对应唯一的映射， 且不会合并不同映射的权限。

连接工作负载

使用您的身份提供方指南中的 SDK 示例， 或直接调用令牌交换端点。有关请求和响应字段、 授权行为及当前限制，请参阅 工作负载身份令牌交换参考资料。

更新访问 Token

如果您直接管理 Token 交换，在将凭据从 Token 服务传递给应用程序时，请将 access_token 和 expires_at 一并传递。 expires_at 字段表示绝对 UTC 到期时间，以秒为单位的 Unix 时间戳 表示。请安排在该时间之前更新 Token，并为时钟 差异和请求延迟预留时间。

expires_in 字段表示 Token 自签发起的有效期，单位为秒。 例如，在 12:00 UTC 签发且 expires_in: 3600 的 Token 会在 13:00 UTC 到期， 即使另一个服务在 12:05 UTC 才收到它。传输和处理 所用的时间不会延长 Token 的有效期。详情请参阅响应 字段。

Token 交换不会返回刷新 Token。如需更新，请使用有效的外部身份 Token 或客户端证书 再次进行交换。

在 Codex 中使用工作负载身份

如果您要在受管理的 ChatGPT 工作空间中运行受信任的 Codex 自动化，请使用此方式。 Codex 会将工作负载映射到 ChatGPT 用户或服务账户，而不是 API 平台服务账户。

请参阅在 Codex 中 使用工作负载身份，了解完整的管理员配置和 运行时操作步骤。该指南涵盖各身份提供方的令牌来源、联合规则、 必需的令牌文件配置、凭据优先级、支持的 Codex 使用界面、轮换和验证。对于可选的审计归因，Codex 接受 OPENAI_WORKLOAD_IDENTITY_CONTEXT；Codex 指南定义了其模式、 隐私限制和审计行为。

使用管理 API，以编程方式管理 Codex 身份提供方和规则。联合规则 参考资料 介绍了如何让一条规则接受多个外部主体，并将它们映射到同一个 ChatGPT 主体。

排查连接问题

OpenAI 拒绝身份令牌

在本地解码令牌，并将其 iss、aud、sub、exp、iat 以及 身份提供方特有的声明与身份提供方配置进行比对。请勿将生产环境的 令牌粘贴到第三方 JWT 工具中。

对于 OpenAI API，还应将令牌属性与所选的服务账户映射进行比对。 对于 Codex，则将这些属性与所选的联合规则进行比对。

OpenAI API 映射不匹配

确认请求使用了预期的身份提供方 ID 和服务账户 ID， 映射已启用，且恰好有一个映射匹配。 请参阅令牌交换错误参考资料， 了解详细的错误类别。

Codex 报告配置不完整

确认 Codex 进程已设置两个必需的工作负载身份环境变量， 且 OPENAI_IDENTITY_TOKEN_FILE 包含指向 当前有效令牌文件的绝对路径。检查文件及其父目录的权限。

Codex 使用了其他凭据

将两个必需的工作负载身份变量都加载到 Codex 进程中。 只要存在其中任一变量，就会优先选择 WIF，而非 API 密钥、访问令牌或 已保存的登录信息。启动一个加载了已下载配置的新进程， 然后再次运行 codex login status。

安全建议

• 为每个应用或工作负载使用专用主体。
• 将生产环境与非生产环境分开。
• 优先使用精确的声明匹配，避免使用过于宽泛的匹配模式。
• 仅授予工作负载所需的访问权限。
• 为访问令牌设置较短的有效期。
• 审查并移除不再使用的身份提供方、映射和规则。
• 审查令牌交换错误和异常访问模式。

相关文档

• 在 Codex 中使用工作负载身份
• Codex 联合规则参考资料
• 使用管理 API 管理 Codex 工作负载身份
• 工作负载身份令牌交换参考资料
• Codex 身份验证
• Codex 环境变量
• Codex 非交互模式