通过工作负载身份联合,受信任的工作负载可以使用已有的身份,无需存储 OpenAI API 密钥或 ChatGPT 凭据。工作负载提交您的身份提供方签发的短期令牌,OpenAI 将其换成短期 OpenAI 访问令牌。
OpenAI API 工作负载也可以通过 X.509 工作负载身份联合,使用经过验证的证书身份换取访问令牌。
您可以在 OpenAI API 或 Codex 中使用工作负载身份联合:
| OpenAI API | Codex | |
|---|---|---|
| OpenAI 身份 | API 平台项目中的服务账号 | 受管理的 ChatGPT 工作空间中的用户或服务账号 |
| 管理员在哪里配置 | OpenAI 平台 | OpenAI 管理门户 |
| 工作负载如何连接 | 通过 OpenAI SDK 或令牌交换端点 | 通过 Codex 环境变量和身份令牌文件 |
| 访问令牌可用于什么 | 调用映射到的服务账号可用的 API,并使用该账号的权限 | 使用映射到的工作空间主体所拥有的 Codex 访问权限 |
这两种方式采用相同的信任模型,但管理方式和运行时配置不同。请先了解下文介绍的共同概念,并阅读身份提供方指南,再按照工作负载所用产品的相应章节进行操作。
- OpenAI API: 请继续阅读在 OpenAI API 中使用工作负载身份。
- Codex: 请参阅在 Codex 中使用工作负载身份。
有关规则的工作方式及其生命周期,请参阅 Codex 联合规则参考。
工作原理
在工作负载连接之前,管理员需配置以下三项:
- 身份提供方指定 OpenAI 应信任哪个外部签发方,以及如何验证该签发方签名的令牌或证书身份。
- 访问规则指定 OpenAI 接受哪些令牌属性,以及工作负载可以使用哪个 OpenAI 身份执行操作。在 OpenAI API 配置中,这称为服务账号映射;在 Codex 配置中,这称为联合规则。
- OpenAI 主体获得相应的访问权限。对于 OpenAI API,主体是平台服务账号。对于 Codex,主体是受管理的工作空间中的 ChatGPT 用户或服务账号。
运行时的流程如下:
- 工作负载收到短期 OIDC JWT 或 SPIFFE JWT-SVID。OpenAI API 工作负载也可以提交 X.509 证书。
- 工作负载提交其外部身份以及所用产品要求的 ID。
- OpenAI 验证令牌或证书,然后评估已配置的映射或规则。
- OpenAI 为映射到的主体返回短期访问令牌。
令牌交换不会创建主体或项目,也不会添加工作空间成员。管理员在配置时创建或选择这些资源。
获取身份令牌
请根据工作负载的运行环境选择指南:
为 OpenAI API 工作负载配置基于证书的令牌交换。
在自行管理的集群中使用投射的服务账号令牌。
使用出站身份联合或 Amazon EKS 投射令牌。
使用托管身份令牌或 AKS 投射的服务账号令牌。
使用元数据服务器提供的身份令牌或 GKE 投射的服务账号令牌。
使用 Oracle 身份域提供的实例主体令牌。
在持续集成工作流中使用 OIDC 令牌。
使用 SPIRE 或兼容的提供方签发的 SPIFFE JWT-SVID。
使用 Idira Secure Workload Access 签发的 SPIFFE JWT-SVID。
在文档所述的配置下,OpenAI 支持与 OIDC 兼容的 JWT 主体令牌,包括 SPIFFE JWT-SVID。如果您使用 OpenAI API,而上方未列出您的 OIDC 提供方,请联系 OpenAI 支持团队。如果您使用 Codex,请在 OpenAI 管理门户中选择自定义 OIDC。
每份 OIDC 提供方指南都说明了如何签发和检查令牌。如果您使用 Codex,只需按照其中的令牌签发步骤操作,然后返回在 Codex 中使用工作负载身份。这些指南中的 OpenAI 配置步骤和 SDK 示例适用于 OpenAI API。X.509 联合仅支持 OpenAI API。
在 OpenAI API 中使用工作负载身份
如果工作负载直接调用 OpenAI API,请使用此方式。您需要具备管理组织的工作负载身份提供方和服务账号映射的权限。
前往组织设置 > 安全 > 工作负载身份提供方。先创建提供方,再从提供方详情页配置其服务账号映射。
X.509 提供方
OpenAI 根据组织现有的双向 TLS 配置验证客户端证书,X.509 提供方从该证书中提取工作负载身份属性。提供方不存储证书,也不维护单独的信任库。
创建提供方之前,请在组织设置 > 安全 > 双向 TLS 中配置并激活作为客户端证书信任锚的受信任证书。双向 TLS 指南介绍了权限、证书要求、激活范围、mTLS 主机、证书链的处理方式、CEL 过滤器和证书轮换。
接下来,创建 X.509 提供方,派生出一个非空的 openai.subject 值,并将该身份映射到一个仅具备工作负载所需权限的项目服务账号。工作负载向 X.509 令牌端点提交证书以获取短期持有者令牌,然后将该令牌和受认可的客户端证书一并发送到 API mTLS 端点。
有关完整的控制台配置步骤和请求流程,请参阅 X.509 证书配置指南。
配置 OIDC 工作负载身份提供方
请为每个受信任的外部签发方创建一个工作负载身份提供方。OpenAI API 的工作负载身份验证支持 OIDC JWT 主体令牌。提供方配置包括:
| 选项 | 说明 |
|---|---|
| 名称 | 工作负载身份提供方在组织内的唯一名称。 |
| OIDC 签发方 URL | 预期的 OIDC 签发方 URL。比较签发方 URL 时会忽略末尾的斜杠。 |
| 受众 | 外部主体令牌中预期的 aud 声明。 |
| 描述 | 工作负载身份提供方的可选描述。 |
| 使用自定义 URL 进行 OIDC 发现 | 启用后,OpenAI 从公开的 HTTPS URL 获取 OIDC 发现元数据。该 URL 可以与令牌签发方的 URL 不同。 |
| 自定义 OIDC 发现 URL | 启用自定义发现时使用的发现基础 URL 或完整的 /.well-known/openid-configuration URL。 |
| 使用上传的 JWKS 验证令牌 | 启用后,OpenAI 使用上传的 JWKS 验证令牌,无需通过 OIDC 发现获取密钥。 |
| JWKS JSON | 启用上传的 JWKS 验证方式时使用的公钥 JWKS 对象。上传的 JWKS 必须包含非空的 keys 数组,且不得包含任何私钥材料。 |
| 属性转换 | 可选的 CEL 表达式,用于从令牌声明派生自定义 openai.* 属性,以判断映射是否匹配。 |
自定义 OIDC 发现与上传 JWKS 两种方式互斥。启用自定义发现后,上传 JWKS 的选项将隐藏。自定义发现 URL 必须是可公开访问的 HTTPS 地址,且不得包含凭据、自定义端口、查询字符串或片段。
如果控制台中没有使用自定义 URL 进行 OIDC 发现选项,请使用标准 OIDC 发现,或启用使用上传的 JWKS 验证令牌。如果选择上传 JWKS,请使用身份提供方发布的公钥 JWKS,并在提供方轮换签名密钥时更新它。
如果令牌签发方与发现文档所在的主机不同,请将 OIDC 签发方 URL 设为令牌的 iss 声明值,并将自定义 OIDC 发现 URL 指向发布提供方发现文档的主机。OpenAI 仍会根据配置的签发方验证令牌。自定义 URL 仅决定 OpenAI 从哪里获取发现元数据和用于验证签名的公钥。
使用 CEL 转换令牌声明
属性转换使用通用表达式语言(CEL)。OpenAI 支持 langdef.md 中规定的标准 CEL 运算符,没有为工作负载身份联合添加自定义函数。每个表达式接收一个根对象:
assertion:经过验证的 JWT 声明集合。
控制台会自动添加 openai. 前缀。请输入后缀(例如 subject)和表达式(例如 assertion.sub)。在此示例中,API 将派生属性存储为 openai.subject。
[
{
"attribute": "openai.subject",
"expression": "assertion.sub"
},
{
"attribute": "openai.repository",
"expression": "assertion.repository"
}
]
请使用 CEL 语言规范定义的语法。例如,您可以使用 assertion.sub 或 assertion.repository 等表达式读取声明值。使用不受支持的语法或函数会导致映射解析失败。
[
{
"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. 前缀,除非您配置了相应的转换,否则这些声明不会影响映射匹配结果。
管理 JWKS 和密钥轮换
OpenAI 使用工作负载身份提供方配置的密钥来源验证 OIDC 主体令牌:
- OIDC 发现: OpenAI 获取签发方的
/.well-known/openid-configuration文档,再从文档中的jwks_uri获取密钥集。OpenAI 会将发现文档和远程 JWKS 的内容缓存 600 秒。 - 自定义 OIDC 发现: OpenAI 从配置的自定义发现基础 URL 获取
/.well-known/openid-configuration文档,再从文档中的jwks_uri获取密钥集。令牌的iss声明仍必须与 OIDC 签发方 URL 匹配。 - 找不到密钥时刷新: 如果在缓存的 JWKS 中找不到令牌的
kid,OpenAI 会刷新 JWKS 并再次查找。如果仍然找不到对应的密钥,OpenAI 会拒绝该令牌。 - 上传的 JWKS: 启用使用上传的 JWKS 验证令牌后,OpenAI 使用上传并保存在提供方配置中的 JWKS,不执行 OIDC 发现,也不从远程获取 JWKS。提供方的更新对令牌交换生效后,新的交换请求将使用保存的 JWKS。
- 密钥集: 一个 JWKS 可以包含多个公钥。每个密钥都必须有唯一且非空的
kid。
轮换签名密钥时,请在轮换期间同时在签发方的 JWKS 中发布新旧公钥。这样,旧密钥签名的令牌仍可使用,OpenAI 也可以接受新密钥签名的令牌。如果使用上传的 JWKS,请先更新提供方配置,再签发带有新 kid 的令牌。如果配置的 JWKS 中没有与签名密钥对应的公钥,OpenAI 会拒绝该令牌。
配置服务账号映射
服务账号映射指定哪些外部身份可以为某个 OpenAI 服务账号获取访问令牌。
对于 X.509 提供方,映射键使用派生的 openai.* 属性。请优先使用精确匹配的 openai.subject 映射。sub、aud 和 iss 等原始 JWT 声明仅适用于 OIDC 提供方。
映射配置包括:
| 选项 | 说明 |
|---|---|
| 名称 | 映射在工作负载身份提供方中的唯一名称。 |
| 键 | 要匹配的属性键。可使用原始令牌声明(例如 sub、aud 或 iss),也可使用派生属性(例如 openai.subject)。 |
| 值 | OpenAI 签发令牌前必须匹配的属性值。 |
| 描述 | 映射的可选描述。 |
| 项目 | 目标服务账号所属的项目。 |
| 服务账号 | 工作负载可以使用的服务账号。您可以在所选项目中创建服务账号,也可以选择现有服务账号。 |
| 权限 | 可选的 API 权限,用于进一步限制通过此映射签发的访问令牌。这些权限不能超出映射到的服务账号所拥有的权限。 |
属性值必须是 JSON 标量值。字符串值可以在非空前缀后使用一个末尾通配符,例如 repo:example/*。不支持单独使用通配符,也不支持在值的中间使用通配符。
有效的通配符值:
repo:openai/*repository:my-org/*
不支持的通配符值:
*repo:*:prodrepo/*/main
控制台在权限下显示映射的访问限制。令牌交换响应则在 scope 属性中以 OAuth 作用域的形式返回相同的限制。映射不能包含管理 API 的作用域,下游 API 仍按常规方式执行授权检查。
映射解析示例
OpenAI 验证外部身份后开始解析映射。OpenAI 根据请求中的 identity_provider_id 和 service_account_id 查找映射,跳过未启用的映射,并且只对每个映射所需的属性求值。只有恰好一个已启用的映射匹配其配置的所有属性时,OpenAI 才会签发令牌。
假设一个 GitHub Actions 令牌包含以下声明:
{
"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"
}
提供方可以派生一个属性:
[
{
"attribute": "openai.repository_ref",
"expression": "assertion.repository + \"@\" + assertion.ref"
}
]
随后,服务账号映射可以要求原始属性和派生属性同时匹配:
| 键 | 值 |
|---|---|
iss |
https://token.actions.githubusercontent.com |
sub |
repo:my-org/my-repo:* |
openai.repository_ref |
my-org/my-repo@refs/heads/main |
这三个值必须全部匹配。sub 值的末尾使用了通配符,因此可匹配任何以 repo:my-org/my-repo: 开头的值。openai.repository_ref 键的值来自属性转换,同名的原始令牌声明不会用于解析此键。
如果一次交换请求匹配多个已启用的映射,OpenAI 会拒绝该请求。OpenAI 要求每个 (provider, service account) 组合的映射唯一,不会合并不同映射的权限。
连接工作负载
您可以使用身份提供方指南中的 SDK 示例,也可以直接调用令牌交换端点。有关请求和响应字段、授权方式及当前限制,请参阅工作负载身份令牌交换参考。
续期访问令牌
如果您直接管理令牌交换,请在令牌服务向应用传递凭据时一并传递 access_token 和 expires_at。expires_at 字段表示绝对到期时间,采用以秒为单位的 UTC Unix 时间戳。请安排在该时间之前续期,并为时钟偏差和请求延迟留出余量。
expires_in 字段表示令牌自签发起的有效时长,单位为秒。例如,UTC 12:00 签发的令牌如果带有 expires_in: 3600,即使另一项服务到 UTC 12:05 才收到它,该令牌仍会在 UTC 13:00 到期。传输和处理所用的时间不会延长令牌的有效期。详情请参阅响应字段。
令牌交换不会返回刷新令牌。要续期,请使用有效的外部身份令牌或客户端证书再次执行交换。
在 Codex 中使用工作负载身份
如果您要在受管理的 ChatGPT 工作空间中运行受信任的 Codex 自动化任务,请使用此方式。Codex 将工作负载映射到 ChatGPT 用户或服务账号,而非 API 平台服务账号。
Codex 工作负载身份联合目前处于测试阶段,您的工作空间必须先启用此功能才能使用。如需申请访问权限,请联系您的 OpenAI 代表或 OpenAI 支持团队。
联合规则参考介绍了如何通过一条规则接受多个外部主体,并将它们映射到同一个 ChatGPT 主体。
排查连接问题
OpenAI 拒绝身份令牌
请在本地解码令牌,将其 iss、aud、sub、exp、iat 以及提供方特有的声明与提供方配置进行核对。请勿将生产环境的令牌粘贴到第三方 JWT 工具中。
如果您使用 OpenAI API,还需将令牌属性与所选的服务账号映射进行核对。如果您使用 Codex,请将这些属性与所选的联合规则进行核对。
OpenAI API 映射不匹配
请确认请求中使用的是预期的身份提供方 ID 和服务账号 ID,映射已启用,并且恰好有一个映射匹配。有关详细的错误类别,请参阅令牌交换错误参考。
Codex 提示配置不完整
请确认 Codex 进程已加载两个必需的工作负载身份环境变量,并确认 OPENAI_IDENTITY_TOKEN_FILE 的值是存放当前有效令牌的文件的绝对路径。请检查该文件及其父目录的权限。
Codex 使用了其他凭据
请将两个必需的工作负载身份环境变量都加载到 Codex 进程中。只要其中任一变量存在,Codex 就会优先选择工作负载身份联合(WIF),其优先级高于 API 密钥、访问令牌和已保存的登录凭据。请使用已下载的配置启动新进程,然后再次运行 codex login status。
安全建议
- 为每个应用或工作负载使用专用主体。
- 将生产环境与非生产环境分开。
- 优先精确匹配声明,避免使用匹配范围过大的模式。
- 仅授予工作负载所需的访问权限。
- 为访问令牌设置较短的有效期。
- 检查并移除不再使用的提供方、映射和规则。
- 检查令牌交换错误和异常访问模式。