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 規則應比對程式碼庫、工作流程檔案、ref 或受保護的環境，而非比對某個組織擁有的所有程式碼庫。

宣告精確比對

宣告精確比對會比較最上層 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"
]

若要要求符合某個程式碼庫，且符合兩個 ref 其中之一：

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。

需要緊急停止或暫時中止時，請使用停用功能。只有在不再需要資源時才將其封存。

限制

若不同信任邊界需要獨立控制簽發者、金鑰、重放防護或生命週期，請為其建立不同的提供者。若工作負載共用信任設定，但需要不同的安全性主體或存取政策，請在同一個提供者下建立不同的規則。