工作負載身份聯合

工作負載身份聯合讓可信自動化能夠使用 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 的詳細資訊，請參閱聯合規則 參考。