工作負載身分聯盟

工作負載身分聯盟可讓受信任的自動化程序使用 Codex，無須儲存個人存取 Token 或其他長效 OpenAI 憑證。工作負載會出示由您現有身分提供者簽發的短效身分 Token。OpenAI 會驗證該 Token，並為您受管理的 ChatGPT 工作區中的使用者或服務帳戶傳回短效存取 Token。

在雲端平台、 Kubernetes、CI 系統，以及其他可簽發 OIDC Token 或 SPIFFE JWT-SVID 的環境中，可使用工作負載身分執行無人值守的 Codex 程序。如需了解共用信任模型和獨立的 OpenAI API 流程， 請參閱工作負載身分概覽。

開始之前

您需要：

• 在 OpenAI 管理入口網站中管理工作負載身分的權限。
• 受管理的 ChatGPT 工作區。
• 具有該工作區有效成員資格的 ChatGPT 使用者或服務帳戶，或在設定期間建立此類帳戶的權限。
• OIDC Token 或 SPIFFE JWT-SVID，且您已知其簽發者、對象及用於識別身分的宣告。
• 能持續更新 Token，並將其保存在絕對路徑下受保護檔案中的執行階段。
• Codex 0.148.0 或更新版本。
• 實際生效的 Codex 身分驗證政策，須允許 ChatGPT 身分驗證， 並允許使用聯盟規則選取的工作區。請參閱強制指定登入 方式或工作區。

OpenAI 不會在交換 Token 時建立主體或授予工作區成員資格。管理員須在工作負載連線前選取或建立主體。建立真人使用者會占用一個工作區席次，且須遵守該工作區的成員資格規則。

在原生 Windows 上，請使用 提高權限的 Windows 沙盒。其他 Windows 沙盒模式 無法防止由模型控制的指令存取身分 Token 檔案。

取得身分 Token

工作負載執行階段負責取得及更新上游身分 Token。Codex 不會代您呼叫雲端中繼資料服務或身分提供者的用戶端程式庫。

請依照提供者的指南設定 Token 簽發方式，並檢查 Token 範例：

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

在本機解碼 Token 範例，並記錄其 iss、aud、sub，以及其他 您準備信任的宣告。解碼不會驗證簽章。切勿將正式環境的 Token 貼到網站或寫入記錄檔。

連接工作負載

管理員須在啟動 Codex 前建立提供者和聯盟規則。

1. 在 OpenAI 管理入口網站中開啟工作負載身分， 然後選取 連接工作負載。
2. 沿用已為 Codex 設定的提供者，或建立新的提供者。提供者預設組態會自動填入 GitHub Actions、Microsoft Entra ID、Google Cloud、AWS、Kubernetes、SPIFFE 和自訂 OIDC 提供者的常用設定。
3. 選取 Codex 及工作負載可使用的受管理工作區。
4. 新增範圍最小且能識別工作負載的條件。可比對主體、精確的宣告值、CEL 條件，或上述條件的組合。新增可接受的對象，以限制規則接受的 Token。所有已設定的比對條件都必須通過。
5. 將規則對應到一名現有的 ChatGPT 使用者或一個服務帳戶，或在設定期間建立其中之一。
6. 審查提供者、條件、工作區、主體、存取範圍， 以及存取 Token 的有效期間。選取 連接工作負載，然後選取 下載設定。

下載的檔案包含非機密的聯盟規則 ID，以及 Codex 讀取身分 Token 的檔案路徑。其中不含任何憑證。

如要將設定流程自動化，請使用工作負載身分管理 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 並非機密資訊，但 Token 檔案屬於機密。 請使用專用目錄中的絕對路徑，例如 /var/run/secrets/openai.com； 該目錄必須由工作負載帳戶擁有，且權限模式須為 0700。 只有受信任的主機程序才應寫入該目錄。請勿將該目錄置於程式碼庫或其他 Codex 工具可存取的路徑中。 請勿讓憑證出現在記錄檔、Shell 歷史紀錄或建置產物中。

新增稽核歸屬資訊

當多個執行階段執行個體共用同一條聯盟規則時， 您可以在 Token 簽發稽核事件中識別各個執行個體。 將選用的 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，但不包含上下文。Token 核發成功的稽核事件 則包含該 ID 和標準化後的上下文。若上下文超出限制或 不符合此結構描述，交換便會失敗並傳回 invalid_grant。

Codex 會在處理程序啟動時讀取上下文，不會將上下文、規則 ID 或 Token 檔案路徑傳遞給由模型控制的 Shell、掛勾或 MCP 伺服器。變更上下文後，請重新啟動 Codex。

保護並輪替 Token 檔案

在受管理的 Linux、macOS 和 WSL 部署中，請將整個 Token 目錄加入受管理需求中的 permissions.filesystem.deny_read 設定：

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

這可防止模型控制的指令讀取目前使用的 Token 或暫時用於替換的 Token，同時仍允許 Codex 主機處理程序使用該 Token 進行交換。針對投影 Token 磁碟區，請禁止讀取整個 Token 掛載點，以及位於其外部的任何底層儲存路徑或解析後的目標路徑。僅靠檔案權限模式及清除環境變數，無法防止以相同使用者身分執行的其他處理程序取得憑證。在原生 Windows 上，請使用上述提升權限的沙盒。

若 Token 來源不會投影出檔案，請讓可信任的主機處理程序在受保護目錄中寫入每個替換檔案，再將其重新命名為目標檔案。原子性重新命名可避免 Codex 讀取到不完整的 Token。例如，您可依照提供者的 Token 指令調整這段由主機管理的更新指令碼。執行指令碼前，請先建立並設定目錄：

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 已透過設定的聯合規則交換 Token。此指令 不會輸出解析出的工作區、身分主體或規則。啟動工作負載之前， 請先在管理入口網站中確認這些值。若 Codex 回報其他 身分驗證方法，表示兩個必要的 WIF 變數未傳入該處理程序。

如果提供者使用 防止斷言重放 功能，且斷言含有 jti 宣告， 這項檢查會耗用該 jti。啟動另一個 Codex 處理程序前， 請寫入包含全新 jti 的新核發斷言。

在相同環境中執行一個簡單的請求：

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

Codex 會交換上游 Token，並將 OpenAI 存取權杖保留在記憶體中。 它不會將任何一項憑證寫入 auth.json、系統金鑰圈或 config.toml。

讓 Token 保持最新狀態

請在上游 Token 到期前更新身分 Token 檔案。當 Codex 需要另一個 OpenAI 存取權杖時，會重新讀取該檔案。OpenAI Token 會在上游 Token 到期或達到聯合規則設定的有效期限時失效，以較早者為準，且有效時間最長為一小時。

管理員啟用重放防護後，每個上游 JWT 都必須具有 唯一的 jti。每次交換前，請寫入包含全新 jti 的新核發斷言， 包括長時間執行的處理程序進行更新時。 未包含 jti 的斷言不受重放防護機制保護。

Codex 會在每個主機處理程序內共用一個記憶體中的交換工作階段。該處理程序中的並行請求會重複使用有效的 OpenAI 存取權杖，並在該權杖到期時共用同一次更新。不同的處理程序會分別進行交換，因此必須使用提供者允許其使用的斷言。

憑證優先順序

兩個必要的工作負載身分變數優先於所有其他憑證來源：

1. 只要存在 OPENAI_FEDERATION_RULE_ID 或 OPENAI_IDENTITY_TOKEN_FILE 其中之一，Codex 就會選擇工作負載身分。
2. 若只存在一個必要變數，Codex 會傳回錯誤，不會改用 API 金鑰、存取權杖或已儲存的登入資訊。
3. 單獨設定 OPENAI_WORKLOAD_IDENTITY_CONTEXT 不會讓 Codex 選擇工作負載身分。
4. 若兩個必要的 WIF 變數皆不存在，Codex 會套用該使用介面的 一般憑證規則。對於允許 API 金鑰身分驗證的使用介面， 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 用戶端絕不會透過各自的通訊協定傳送上游身分 Token。

變更或移除存取權

對規則的主旨、對象、宣告、CEL 條件、範圍或 Token 有效期限所做的變更，會套用至新的交換。變更前核發的 Token 可能持續有效，直到其有效期限結束。

停用提供者或規則可立即停止存取。停用會阻止新的交換，並撤銷已透過該資源核發的 OpenAI 存取權杖。封存對存取權有相同的影響，且無法復原。變更提供者的信任設定，也會在新的信任設定生效前撤銷已核發的 Token。

稽核變更

建立、更新及封存提供者與聯合規則，都會產生稽核事件。 請依照 Compliance API 與稽核事件 指南，匯出工作區支援的事件。 將這些事件與身分提供者的核發記錄相互比對， 且不要在任一系統中記錄上游斷言或 OpenAI 存取權杖。

當處理程序提供 OPENAI_WORKLOAD_IDENTITY_CONTEXT 時， Token 核發成功的稽核事件也會包含上述穩定的歸屬 ID， 以及標準化後的上下文。

疑難排解

如需提供者驗證、限制及 CEL 的詳細資訊，請參閱聯盟規則 參考資料。