Codex 联合规则参考资料

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

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

有关设置步骤，请参阅在 Codex 中 使用工作负载身份。要通过代码管理规则，请参阅 工作负载身份 Admin API。

规则模型

在进行交换之前，安全主体及其工作空间成员资格必须已存在。工作负载连接时，规则不会创建用户、服务账户或成员资格。

身份检查如何组合

规则可以使用以下检查：

请至少设置一项主体检查、精确声明检查或 CEL 检查。仅凭接受的受众无法识别工作负载。如果您配置了多种检查类型，每种检查都必须通过。

首先进行提供方验证。规则无法覆盖提供方的签发方、签名、过期时间、断言有效期、重放检查或提供方级别的 CEL 检查。

主体匹配

如果一个稳定的 sub 就能标识工作负载，请使用精确主体匹配：

repo:example-company/payments:environment:production

在末尾添加一个 * 即可进行前缀匹配：

system:serviceaccount:production:codex-*

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

如果可以通过更稳定的声明区分具有特权的工作负载，就不要使用范围过宽的前缀。例如，GitHub 规则应匹配特定的代码仓库、工作流程文件、引用或受保护的环境，而不是某个组织拥有的所有代码仓库。

精确声明

精确声明检查会比较顶层 JWT 声明，不会转换其类型。字符串仅匹配相同的字符串，布尔值仅匹配相同的布尔值，数字则匹配相同的数值。不支持将列表和对象用作精确匹配值。

例如：

12345{
  "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"
]

要要求匹配特定代码仓库以及两个引用中的任意一个：

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 以外的标识符。 请保持表达式简短；如果精确检查 能够表达相同的策略，请优先使用精确检查。

声明缺失、使用不受支持的操作、结果不是布尔值或求值出错，都会导致交换被拒绝。

受众匹配

提供方可以设置一个预期受众，也可以改为在规则中设置一个或多个 接受的受众。规则设有受众列表时， Token 的 aud 声明中必须至少有一个值出现在该列表中。

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

受众匹配和身份检查需要同时满足。即使受众匹配，也无法弥补未通过的主体检查、精确声明检查或 CEL 检查。

安全主体数量限制

一条规则只能映射到一个安全主体：

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

这样，工作负载副本、作业或获准的主体就可以代表同一个用户或服务账户执行操作，但一条规则无法根据声明选择不同的安全主体。当工作负载需要不同的安全主体、工作空间、作用域或 Token 有效期时，请创建独立的规则。

多条规则可以指向同一个安全主体。如果您需要为每个工作负载独立控制生命周期，或在审计时更清楚地识别操作归属，请使用不同的规则。

权限范围与授权

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

如果您省略权限范围，OpenAI 会使用标准 Codex 权限范围：openid、 profile、email 和 Codex 本地访问权限。如果您通过 Admin API 设置权限范围， 请包含 chatgpt.workspace.feature.allow-codex-local-access.access，并且 仅使用这四个受支持的值。

请先按照最小权限原则选择安全主体并设置工作空间权限。将规则的权限范围作为第二层限制，而非主要的授权边界。

Token 有效期

将 OpenAI 访问令牌的有效期设置为 60 至 3,600 秒。OpenAI 会采用以下两者中较短的时间：

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

较短的有效期可以缩短策略修改后已签发 Token 仍然有效的时间，但会增加交换频率。除非您的工作负载需要不同的权衡，否则可以先将有效期设为 10 分钟。

重放保护

提供方级别的重放保护使用 JWT 的 jti 声明。当管理员 开启 防止断言重放 ，且 Token 包含非空的 jti 时， 在断言过期之前，OpenAI 对该提供方只接受该 jti 一次。

工作负载必须在每次交换前获取包含新 jti 的新断言， 包括在交换结果未知时进行重试的情况。不包含 jti 的断言仍可使用，但不受重放保护。如果 jti 的值为空、null 或 非字符串，则无法通过验证。

修改、禁用与归档

对身份检查、权限范围或 Token 有效期的常规修改适用于新的交换。修改前签发的访问令牌可能会一直有效，直到其原有 TTL 结束。

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

需要紧急停止或临时暂停时，请使用禁用功能。只有在您不再需要某项资源时，才将其归档。

限制

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