OpenAI Codex 联合规则参考

联合规则决定哪些已经验证的工作负载身份可代表一个 ChatGPT 用户或服务账户。OpenAI 只评估 Codex 进程指定的规则，不搜索所有规则。每条规则有一个目标主体，可接受一个或多个上游身份；通过末尾前缀通配或 CEL 接受多个主体，也可为同一目标创建多条规则。

规则模型

交换前主体及工作区成员关系必须已存在，规则不在连接时创建用户、服务账户或成员关系。

身份检查如何组合

至少设置 subject、精确声明或 CEL 检查之一。只设受众不足以识别工作负载，多类检查同时配置时必须全部通过。先执行提供商验证，规则不能覆盖 issuer、签名、到期、声明寿命、重放或提供商 CEL 检查。

主体匹配

稳定的 sub 能识别工作负载时使用精确值：

来源示例 1（text）：

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

repo:example-company/payments:environment:production

一个末尾 * 表示前缀匹配：

来源示例 2（text）：

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

system:serviceaccount:production:codex-*

通配符必须在最后且前缀非空，不支持 *、repo:*:production、repo/*/main。能用稳定声明区分高权限工作负载时不要用宽泛前缀；GitHub 应限定仓库、工作流文件、ref 或受保护环境，而非信任整个组织所有仓库。

精确声明

比较顶层 JWT 标量，不转换类型：字符串只匹配相同字符串、布尔只匹配相同布尔、数字按数值匹配，不支持列表和对象作为精确值。

来源示例 3（json）：

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

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

不要在精确声明映射中包含 sub，应使用 subject 字段或 CEL。嵌套声明和列表成员检查使用 CEL。

CEL 条件

assertion 包含完整已验证 JWT 声明，表达式必须返回布尔值。采用受限 CEL 子集以保持可预测。接受一组精确主体：

来源示例 4（text）：

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

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

要求仓库及两个 ref 之一：

来源示例 5（text）：

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

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

读取嵌套或可选声明：

来源示例 6（text）：

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

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

支持 has、size、contains、startsWith、endsWith。不支持正则、all/exists 等集合迭代宏、任意函数或 assertion 之外标识符。保持表达式简短，同样策略优先用精确检查。缺声明、不支持操作、非布尔结果或求值错误都会拒绝交换。

受众匹配

提供商可设一个预期受众，规则可设置一个或多个接受受众。规则设列表时，令牌 aud 至少一项须在列表内。能指定时使用 OpenAI 专属受众。SPIFFE JWT-SVID 规则必须设置接受受众；OIDC 提供商未设受众时规则也必须设置。受众与其他身份检查累加，不能弥补 subject、精确声明或 CEL 不通过。

主体基数

一条规则只映射一个目标主体：

来源示例 7（text）：

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

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

支持副本、任务或多个获准外部主体代表同一用户/服务账户，不能按声明动态选择其他主体。目标主体、工作区、scope 或寿命不同应建不同规则。同一目标可有多条规则，以便独立生命周期控制和审计归因。

Scope 与授权

规则可收窄 OAuth scopes，但不能授予主体或工作区本来没有的权限。省略时用标准 Codex scopes：openid、profile、email 和 Codex 本地访问。通过 Admin API 指定时，必须包含 chatgpt.workspace.feature.allow-codex-local-access.access，且只能使用这四个值。先选最小权限主体和工作区，scope 是第二层限制。

令牌寿命

配置 60—3600 秒，实际采用上游身份令牌剩余寿命与规则配置寿命的较短者。短期令牌减少策略编辑后旧令牌继续有效的时间，但增加交换频率。10 分钟可作为平衡起点，按工作负载调整。

重放保护

提供商启用 Prevent assertion replay 且 JWT jti 非空时，同一提供商在声明到期前只接受该 jti 一次。每次交换前都要取新 jti 的声明，交换结果未知后的重试也一样。无 jti 的声明仍可使用，但无重放保护；空、null 或非字符串 jti 不合格。

编辑、停用与归档

身份检查、scope、寿命的普通编辑作用于新交换；此前令牌可保持有效至原 TTL。停用规则或提供商会阻止新交换并撤销经其签发的令牌；归档同样处理且不可撤销。修改 issuer/JWKS 等提供商信任，在新配置生效前撤销已签发令牌。紧急停止或临时暂停用停用，不再需要时才归档。

限制

需要独立 issuer、密钥、重放或生命周期控制的边界用不同提供商；共享信任但目标主体或策略不同的工作负载，在同一提供商下建独立规则。