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

Codex 联合身份规则参考

根据外部工作负载的声明匹配一个 ChatGPT 主体,并通过访问策略限定其访问范围。

联合身份规则决定哪些已验证的工作负载身份可以代表指定的 ChatGPT 用户或服务账号执行操作。OpenAI 只评估 Codex 进程指定的规则,不会遍历所有规则来查找匹配项。

每条规则只有一个目标主体,但可以接受一个或多个上游身份。要在同一条规则中接受多个主题,请使用末尾带通配符的主题前缀,或设置 CEL 条件。您也可以为同一主体创建多条规则。

规则模型

组成部分 用途
身份提供方 定义 OpenAI 信任的签发者和签名密钥。
工作空间 将获得的访问权限限定在一个受管理的 ChatGPT 工作空间内。
主体 指定该工作空间中的一个现有用户或服务账号。
身份检查 限定哪些已验证的身份令牌可以使用这条规则。
权限范围 可进一步缩小现有的 Codex OAuth 权限范围。
访问令牌有效期 将 OpenAI 访问令牌的有效期限定在 60 至 3,600 秒之间。

在交换令牌之前,主体必须已存在,且已是目标工作空间的成员。工作负载连接时,规则不会创建用户或服务账号,也不会将其添加为工作空间成员。

如何组合身份检查

一条规则可以使用以下检查:

检查项 检查方式 适用场景
主题 精确匹配 sub 值,或使用末尾带一个 * 的模式进行前缀匹配。 单个工作负载身份或受控的主题命名空间。
接受的受众 指定 1 至 32 个受众字符串。令牌必须至少包含其中一个。 专门为 OpenAI 签发的令牌。
精确匹配声明 对最多 32 个顶层声明的标量值进行精确匹配。 稳定的字符串、数字、布尔值或 null。
CEL 条件 对名为 assertion 的已验证声明映射求值,结果必须为布尔值。 列表、嵌套声明或一组允许的值。

主题检查、声明精确匹配和 CEL 检查至少要设置一项。仅指定接受的受众无法识别工作负载。如果您配置了多种检查,每种检查都必须通过。

OpenAI 首先执行身份提供方级别的验证。规则不能覆盖该级别的签发者、签名、过期时间、断言有效期、重放或 CEL 检查。

主题匹配

如果一个稳定的 sub 值就能标识工作负载,请精确匹配主题:

repo:example-company/payments:environment:production

在末尾使用一个 * 即可按前缀匹配:

system:serviceaccount:production:codex-*

通配符必须是最后一个字符,且前缀不能为空。OpenAI 不接受 *、repo:*:production 或 repo/*/main。

如果可以用更稳定的声明来区分具有特权的工作负载,请勿使用匹配范围过宽的前缀。例如,GitHub 规则应匹配特定的代码仓库、工作流文件、Git 引用或受保护的环境,避免匹配某个组织名下的所有代码仓库。

精确匹配声明

精确匹配只比较 JWT 的顶层声明,不转换类型。字符串只能匹配相同的字符串,布尔值只能匹配相同的布尔值,数字只能匹配相同的数值。精确匹配不支持列表或对象值。

例如:

{
  "repository": "example-company/payments",
  "ref": "refs/heads/main",
  "environment": "production"
}

请勿在精确匹配声明的映射中包含 sub。请使用主题字段或 CEL。要检查身份提供方的嵌套声明,或判断某个值是否在列表中,请使用 CEL。

CEL 条件

CEL 条件通过 assertion 访问完整的、已验证的 JWT 声明映射,且必须返回 true 或 false。OpenAI 仅支持 CEL 的一个有限子集,以确保规则的求值行为可预测。

要在一条规则中允许一组精确指定的主题:

assertion.sub in [
  "repo:example-company/payments:environment:production",
  "repo:example-company/billing:environment:production"
]

要限定代码仓库,并要求 Git 引用匹配以下两者之一:

assertion.repository == "example-company/payments" &&
assertion.ref in ["refs/heads/main", "refs/heads/release"]

要读取嵌套声明或可选声明:

has(assertion.environment) &&
assertion.environment == "production"

支持的辅助函数包括 has、size、contains、startsWith 和 endsWith。不支持正则表达式匹配、all 或 exists 等集合迭代宏、任意函数,以及 assertion 以外的标识符。请保持表达式简短。如果精确匹配能表达相同的策略,请优先使用精确匹配。

如果声明缺失、操作不受支持、结果不是布尔值或求值出错,OpenAI 会拒绝令牌交换请求。

受众匹配

身份提供方可以设置一个预期受众。您也可以改为在规则中设置一个或多个接受的受众。如果规则设置了受众列表,令牌的 aud 声明中必须至少有一个值出现在该列表中。

如果身份提供方支持专用受众,请为 OpenAI 使用专用受众。SPIFFE JWT-SVID 规则必须设置接受的受众。如果身份提供方未在提供方级别定义受众,OIDC 规则也必须设置接受的受众。

受众匹配和身份检查必须同时通过。即使受众匹配,只要主题检查、声明精确匹配或 CEL 检查未通过,令牌交换请求仍会被拒绝。

规则与主体的对应关系

每条规则恰好映射到一个主体:

many accepted external identities -> one federation rule -> one OpenAI principal

这样,工作负载副本、作业或获准的主题都可以代表同一个用户或服务账号执行操作。一条规则不能根据声明选择不同的主体。如果工作负载需要不同的主体、工作空间、权限范围或令牌有效期,请分别创建规则。

多条规则可以指向同一个主体。如果您需要独立管理各工作负载的规则生命周期,或需要在审计时更清楚地确定操作来自哪个工作负载,请分别设置规则。

权限范围与授权

规则可以缩小所签发访问令牌的 OAuth 权限范围。规则无法授予目标主体或工作空间尚未拥有的权限。

如果您未指定权限范围,OpenAI 会使用标准 Codex 权限范围:openid、profile、email 和 Codex 本地访问。如果您通过 Admin API 设置权限范围,必须包含 chatgpt.workspace.feature.allow-codex-local-access.access,且只能使用上述四个受支持的值。

请先按照最小权限原则选择主体并设置工作空间权限。规则的权限范围仅用于进一步限制访问,主要的授权边界应由主体和工作空间权限确定。

令牌有效期

请将 OpenAI 访问令牌的有效期设置为 60 至 3,600 秒。OpenAI 取以下两者中的较短值:

  • 上游身份令牌的剩余有效期。
  • 规则中配置的访问令牌有效期。

缩短有效期可以减少已签发令牌在策略修改后仍然有效的时间,但也会增加令牌交换频率。您可以先将有效期设为 10 分钟,除非工作负载需要在这两方面做出不同的权衡。

重放防护

身份提供方级别的重放防护使用 JWT 的 jti 声明。如果管理员启用了防止断言重放,且令牌包含非空的 jti,则在断言过期前,OpenAI 对该身份提供方仅接受该 jti 一次。

每次交换令牌前,工作负载都必须获取包含新 jti 的新断言。即使上一次交换的结果未知,重试时也必须这样做。不含 jti 的断言仍可使用,但不受重放防护。如果 jti 的值为空字符串、null 或非字符串值,则无法通过验证。

修改、停用与归档

对身份检查、权限范围或令牌有效期的常规修改适用于新的令牌交换请求。修改前签发的访问令牌可能会一直有效,直到原定的有效期(TTL)届满。

停用规则或身份提供方会阻止新的令牌交换,并撤销通过该规则或身份提供方签发的 OpenAI 访问令牌。归档具有相同的效果,且无法撤销。如果更改身份提供方的信任配置(例如签发者或 JWKS 设置),OpenAI 会在新配置生效前撤销已签发的令牌。

如果需要紧急停止或暂时中止使用,请停用相应资源。只有在您不再需要该资源时,才将其归档。

限制

资源 限制
每个组织中未归档的身份提供方数量 50
每个身份提供方下未归档的规则数量 50
每条规则中精确匹配的声明数量 32
每条规则接受的受众数量 32 个不同的值
主题长度 4,096 字节
精确匹配声明的映射或 CEL 条件 16 KiB
访问令牌有效期 60 至 3,600 秒

如果不同的信任边界需要独立控制签发者、密钥、重放防护或生命周期,请分别创建身份提供方。如果多个工作负载共享同一信任配置,但需要不同的主体或访问策略,请在同一身份提供方下分别创建规则。