工作负载身份联合

工作负载身份联合让可信自动化能够使用 Codex，而无需存储 个人访问令牌或其他长期有效的 OpenAI 凭据。你的工作负载会 提供由你已在使用的提供商签发的短期身份令牌。 OpenAI 验证该令牌，并为你所管理的 ChatGPT 工作区中的用户或 服务账号返回短期访问令牌。

在云平台、Kubernetes、CI 系统以及其他能够签发 OIDC 令牌或 SPIFFE JWT-SVID 的环境中，可对无人值守的 Codex 进程使用工作负载身份。 有关共享信任模型和单独的 OpenAI API 流程，请参阅 工作负载身份概述。

开始之前

你需要：

• 在 OpenAI Admin Portal 中管理工作负载身份的权限。
• 一个受管理的 ChatGPT 工作区。
• 一个属于该工作区活跃成员的 ChatGPT 用户或服务账号， 或者在设置期间创建此类账号的权限。
• 一个已知其签发者、受众和标识声明的 OIDC 令牌或 SPIFFE JWT-SVID。
• 一个能够通过绝对路径将该令牌持续更新并保存在受保护文件中的 运行时。
• Codex 0.148.0 或更高版本。
• 一项有效的 Codex 身份验证策略，允许使用 ChatGPT 身份验证以及 联合规则所选的工作区。请参阅强制使用登录 方式或工作区。

OpenAI 不会在令牌交换期间创建主体或工作区成员资格。 管理员需在工作负载连接之前选择或创建主体。 创建人类用户会占用一个工作区席位，并遵循该工作区的 成员资格规则。

在原生 Windows 上，请使用提升权限的 Windows 沙箱。其他 Windows 沙箱模式 无法保护身份令牌文件免受模型控制的命令访问。

获取身份令牌

你的工作负载运行时负责获取并刷新上游身份令牌。Codex 不会 代表你调用云元数据服务或身份提供商客户端库。

按照你的提供商指南配置令牌签发并检查 示例令牌：

• Microsoft Azure
• AWS
• Google Cloud
• Oracle Cloud Infrastructure
• GitHub Actions
• Kubernetes
• SPIFFE

在本地解码示例令牌，并记录其 iss、aud、sub 以及你计划信任的任何其他 声明。解码不会验证签名。请勿将 生产令牌粘贴到网站中或写入日志。

连接工作负载

管理员需先创建提供商和联合规则，然后再启动 Codex。

1. 在 OpenAI Admin Portal 中打开工作负载身份， 然后选择 Connect workload。
2. 复用为 Codex 配置的提供商，或创建一个新提供商。提供商预设会为 GitHub Actions、Microsoft Entra ID、Google Cloud、 AWS、Kubernetes、SPIFFE 和自定义 OIDC 提供商填充常用设置。
3. 选择 Codex 以及工作负载可使用的受管理工作区。
4. 添加能够标识工作负载的最严格条件。匹配主体、 精确声明、CEL 条件或它们的组合。添加可接受的受众， 以限制规则接受哪些令牌。配置的每个匹配器都必须通过。
5. 将规则映射到一个现有的 ChatGPT 用户或服务账号，或者在 设置期间创建一个。
6. 检查提供商、条件、工作区、主体、作用域和访问 令牌生命周期。选择 Connect workload，然后选择 Download config。

下载的文件包含一个非机密的联合规则 ID，以及 Codex 读取身份令牌的路径。该文件不包含凭据。

如需自动完成设置，请使用工作负载身份 Admin API。有关匹配器 行为和示例，请参阅联合规则 参考。

配置 Codex 进程

启动 Codex 的进程需要以下两个工作负载身份变量：

export OPENAI_FEDERATION_RULE_ID="idpm_..."
export OPENAI_IDENTITY_TOKEN_FILE="/var/run/secrets/openai.com/identity-token"

OPENAI_FEDERATION_RULE_ID 不是机密，但令牌文件是。请在专用目录中使用绝对 路径，例如 /var/run/secrets/openai.com；该目录应归 工作负载账号所有，模式为 0700。只有可信主机进程才能在 其中写入。该目录应位于仓库以及 Codex 工具可访问的其他路径之外。 不要让凭据出现在日志、shell 历史记录和构建产物中。

添加审计归属信息

当多个运行时实例共享一个联合规则时，可以在令牌签发审计事件中 标识每个实例。将可选的 OPENAI_WORKLOAD_IDENTITY_CONTEXT 变量设置为编码成 字符串的 JSON 对象：

export OPENAI_WORKLOAD_IDENTITY_CONTEXT='{
  "instance_id": "runner-42",
  "display_name": "payments-prod",
  "labels": {
    "environment": "production",
    "region": "us-west-2"
  }
}'

该对象必须包含 instance_id。它还可以包含 display_name 和最多 八个标签。编码后的对象最大为 1,024 字节。instance_id 和 display_name 最多可包含 128 个字符。标签键最多可包含 64 个 字符，标签值最多可包含 256 个字符。

标识符必须以 ASCII 字母或数字开头。之后的值可以包含 字母、数字、.、_、:、/、@ 和 -。标签键支持字母、 数字、.、_ 和 -。

OpenAI 将此上下文视为客户端报告的审计归属信息，而不是经过验证的 工作负载身份。它不会影响身份验证、授权、规则 匹配、作用域、速率限制、吊销、功能开关或指标。请勿在 其中放入凭据、机密、个人数据、提示词、模型输出或其他客户内容。

对于有效的上下文，OpenAI 会派生一个稳定的归属 ID，其作用域限定于租户、 提供商、联合规则和 instance_id。用于归属时，访问令牌 包含该 ID，但不包含上下文。成功的令牌签发审计事件 包含该 ID 和规范化后的上下文。上下文超出限制或 违反此架构时，交换将失败并返回 invalid_grant。

Codex 会在进程启动时读取上下文，并且不会将它、规则 ID 或令牌文件路径传递给模型控制的 shell、hook 或 MCP 服务器。 更改上下文后请重启 Codex。

保护并轮换令牌文件

对于受管理的 Linux、macOS 和 WSL 部署，请将整个令牌目录添加到 受管理要求中的 permissions.filesystem.deny_read：

[permissions.filesystem]
deny_read = ["/var/run/secrets/openai.com"]

这会阻止模型控制的命令读取有效令牌或 临时替换文件，同时 Codex 主机进程仍可使用令牌进行 交换。对于投射令牌卷，应拒绝访问整个令牌挂载点，以及 位于其外部的任何后备路径或解析后的目标路径。仅设置文件模式和清理环境变量 无法保护凭据不被以同一用户身份运行的其他进程访问。 在原生 Windows 上，请使用上文所述的提升权限沙箱。

对于不会投射文件的令牌来源，请让可信主机进程在 该受保护目录内写入每个替换文件，然后通过重命名将其移至正确位置。原子 重命名可防止 Codex 读取不完整的令牌。例如，可根据 提供商的令牌命令调整以下由主机所有的刷新脚本。运行脚本前先预配 目录：

set -eu
TOKEN_DIR="/var/run/secrets/openai.com"
TOKEN_FILE="$TOKEN_DIR/identity-token"
umask 077
TOKEN_TEMP="$(mktemp "$TOKEN_DIR/.identity-token.XXXXXX")"
trap 'rm -f -- "$TOKEN_TEMP"' EXIT
trap 'exit 1' HUP INT TERM
your-identity-provider-command > "$TOKEN_TEMP"
test -s "$TOKEN_TEMP"
mv -f -- "$TOKEN_TEMP" "$TOKEN_FILE"

请在 Codex 无法控制的任何 shell 或工具之外运行刷新进程。刷新和清理期间 始终保持读取拒绝。即使强制停止后 留下临时文件，该文件也必须保留在被拒绝访问的 目录中。请勿将工作负载身份设置放入 config.toml。

验证连接

加载下载的环境并检查所选的身份验证方式：

. ./workload-identity-idpm_example.env
codex login status

在 PowerShell 中：

$env:OPENAI_FEDERATION_RULE_ID = "idpm_..."
$env:OPENAI_IDENTITY_TOKEN_FILE = "C:\run\openai\identity-token"
codex login status

检查成功时会输出 Logged in using workload identity。这可以确认 Codex 已通过配置的联合规则交换令牌。该命令 不会输出解析后的工作区、主体或规则。启动工作负载前，请在 Admin Portal 中确认这些值。如果 Codex 报告了其他 身份验证方式，说明两个必需的 WIF 变量未传递到该进程。

如果提供商使用 Prevent assertion replay，并且断言含有 jti 声明，此检查会使用该 jti。启动另一个 Codex 进程前， 请写入一个带有新 jti 的新签发断言。

从同一环境运行一个小型请求：

codex exec "Reply with only: workload identity is working"

Codex 会交换上游令牌，并将 OpenAI 访问令牌保存在内存中。 它不会将任一凭据写入 auth.json、系统密钥环或 config.toml。

保持令牌为最新状态

在上游令牌到期前刷新身份令牌文件。Codex 在需要另一个 OpenAI 访问令牌时会重新读取该文件。OpenAI 令牌会在 上游令牌到期时间或联合规则生命周期中较早的时间到期， 且有效期绝不会超过一小时。

管理员开启重放保护后，每个上游 JWT 必须具有唯一的 jti。每次交换前（包括长时间运行进程中的刷新）都要写入一个 带有新 jti 的新签发断言。不含 jti 的断言不会获得重放保护。

Codex 会在每个主机进程内共享一个内存交换会话。该进程中的并发 请求会复用有效的 OpenAI 访问令牌，并在令牌到期时共享一次刷新。 不同进程会分别执行交换，因此它们需要 提供商允许其使用的断言。

凭据优先级

两个必需的工作负载身份变量优先于所有其他 凭据来源：

1. 如果存在 OPENAI_FEDERATION_RULE_ID 或 OPENAI_IDENTITY_TOKEN_FILE 中的任意一个，Codex 会选择工作负载身份。
2. 如果只存在一个必需变量，Codex 会返回错误。它不会 回退到 API key、访问令牌或存储的登录信息。
3. 仅设置 OPENAI_WORKLOAD_IDENTITY_CONTEXT 不会选择工作负载身份。
4. 如果两个必需的 WIF 变量都不存在，Codex 会应用该界面的常规 凭据规则。对于允许使用 API key 身份验证的界面，CODEX_API_KEY 在 codex exec、 codex review、TypeScript SDK 和 codex exec-server --remote 上具有优先级。其他 界面可以使用 CODEX_ACCESS_TOKEN 或存储的登录信息。

SDK 的 apiKey 选项会变为 CODEX_API_KEY，但当任一必需的 WIF 变量存在时，WIF 仍然优先。 使用 WIF 时请省略该选项，以免工作负载携带未使用的长期有效凭据。

如需在不中断服务的情况下迁移现有工作负载，请在其当前 凭据仍然可用时配置 WIF。启动一个包含两个必需 WIF 变量的新进程；即使旧凭据仍然存在，WIF 也会优先。 工作负载通过 WIF 成功运行后，从其运行时 和机密存储中移除旧凭据，然后将其吊销。在吊销之前，可以通过 移除两个必需的 WIF 变量并启动新进程来回滚。

支持的 Codex 界面

在拥有 Codex 进程的机器上配置工作负载身份。

远程 app-server 和 exec-server 客户端绝不会通过其协议发送上游身份 令牌。

更改或移除访问权限

对规则的主体、受众、声明、CEL 条件、作用域或令牌 生命周期所做的更改适用于新的交换。更改前签发的令牌可能会在其生命周期 结束前保持有效。

禁用提供商或规则可立即停止访问。禁用会阻止新的 交换，并吊销已通过该资源签发的 OpenAI 访问令牌。 归档具有相同的访问效果，并且无法撤销。更改提供商 信任关系也会在新信任关系生效前吊销已签发的令牌。

审计更改

创建、更新和归档提供商及联合规则都会生成审计 事件。使用 Compliance API 和审计事件 指南导出你的工作区 支持的事件。将这些事件与你的身份提供商签发日志进行关联，并且不要在 任一系统中记录上游断言或 OpenAI 访问令牌。

当进程提供 OPENAI_WORKLOAD_IDENTITY_CONTEXT 时，成功的 令牌签发审计事件还会包含上述稳定归属 ID 和 规范化上下文。

问题排查

有关提供商验证、限制和 CEL 的详细信息，请参阅联合规则 参考。