如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

Codex 聯合規則參考指南

根據外部工作負載的宣告,將符合條件的身分對應至單一 ChatGPT 主體,並套用限定存取範圍的政策。

聯合規則決定哪些通過驗證的工作負載身分可以代表特定的 ChatGPT 使用者或服務帳戶執行操作。OpenAI 只評估 Codex 程序指定的規則,不會搜尋所有規則來尋找相符項目。

每條規則只有一個目標主體,但可接受一或多個上游身分。若要讓同一條規則接受多個主旨,可在主旨前綴後加上萬用字元,或設定 CEL 條件。你也可以為同一個主體建立多條規則。

規則模型

組成項目 用途
提供者 定義 OpenAI 信任的簽發者與簽署金鑰。
工作區 將取得的存取權限定於單一受管理的 ChatGPT 工作區。
主體 指定該工作區中一個既有的使用者或服務帳戶。
身分檢查 限定哪些已通過驗證的身分權杖可以使用這條規則。
授權範圍 可視需要縮小既有的 Codex OAuth 授權範圍。
存取權杖有效期限 將 OpenAI 存取權杖的有效期限限定為 60 至 3,600 秒。

交換權杖前,主體必須已存在,且已是該工作區的成員。工作負載連線時,規則不會建立使用者、服務帳戶或工作區成員資格。

身分檢查如何搭配使用

規則可使用下列檢查:

檢查項目 比對方式 適用情境
主旨 精確比對 sub 值,或使用結尾帶有單一 * 的模式比對前綴。 單一工作負載身分,或受控的主旨命名空間。
接受的對象 可指定 1 至 32 個對象字串。權杖必須包含其中至少一個。 專為 OpenAI 簽發的權杖。
精確宣告比對 最多可精確比對 32 個頂層宣告的純量值。 固定的字串、數字、布林值或 null。
CEL 條件 以布林運算式檢查名為 assertion 的已驗證宣告對應表。 清單、巢狀宣告或一組允許的值。

主旨比對、精確宣告比對與 CEL 條件至少須設定一項。僅設定接受的對象不足以識別工作負載。若設定多種檢查,每一種都必須通過。

系統會先執行提供者層級的驗證。規則無法覆寫提供者對簽發者、簽章、到期時間、判斷提示有效期限及重放的檢查,也無法覆寫提供者層級的 CEL 檢查。

主旨比對

如果單一且穩定的 sub 值就能識別工作負載,請精確比對主旨:

repo:example-company/payments:environment:production

在結尾加上一個 * 即可比對前綴:

system:serviceaccount:production:codex-*

萬用字元必須是最後一個字元,且前綴不得為空。OpenAI 不接受 *、repo:*:production 或 repo/*/main。

如果有更穩定的宣告可用來區分具有特殊權限的工作負載,請避免使用涵蓋範圍過廣的前綴。例如,GitHub 規則應比對特定的程式碼庫、工作流程檔案、Git 參照或受保護的環境,避免將某個組織擁有的所有程式碼庫都納入比對範圍。

精確宣告比對

精確比對頂層 JWT 宣告時,系統不會轉換值的型別。字串只與相同的字串相符,布林值只與相同的布林值相符,數字則須數值相等。精確比對不支援清單或物件值。

例如:

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

若要限定特定程式碼庫,且要求 Git 參照符合下列兩者之一:

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 以外的識別碼。請盡量縮短運算式。如果精確比對就能表達相同的政策,請優先使用精確比對。

若宣告不存在、使用不支援的操作、結果不是布林值,或評估時發生錯誤,系統就會拒絕交換權杖。

對象比對

提供者可設定一個預期對象。你也可以改在規則中設定一或多個接受的對象。如果規則設有對象清單,權杖的 aud 宣告中至少要有一個值出現在該清單中。

如果提供者支援,請為 OpenAI 設定專用對象。SPIFFE JWT-SVID 規則必須設定接受的對象。如果 OIDC 提供者未在提供者層級定義對象,OIDC 規則也必須設定接受的對象。

對象比對與身分檢查必須同時通過。即使對象相符,只要主旨比對、精確宣告比對或 CEL 檢查未通過,交換仍會失敗。

規則與主體的對應關係

每條規則只對應到一個主體:

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

因此,多個工作負載複本、作業或經核准的主旨都可以代表同一個使用者或服務帳戶執行操作。同一條規則無法依據宣告選擇不同的主體。如果工作負載需要不同的主體、工作區、授權範圍或權杖有效期限,請分別建立規則。

多條規則可以指定同一個目標主體。如果需要獨立管理各個工作負載的生命週期,或需要在稽核時更清楚地辨識是哪個工作負載執行了操作,請分別建立規則。

授權範圍與權限

規則可以縮小所簽發存取權杖的 OAuth 授權範圍,但無法授予目標主體或工作區原本沒有的權限。

如果省略授權範圍,OpenAI 會使用標準的 Codex 授權範圍:openid、profile、email 及 Codex 本機存取權。如果透過管理 API 設定授權範圍,必須包含 chatgpt.workspace.feature.allow-codex-local-access.access,且只能使用上述四個支援的值。

請先依最小權限原則選擇主體及工作區權限,以此界定主要的授權邊界,再使用規則的授權範圍進一步限制存取權。

權杖有效期限

請將 OpenAI 存取權杖的有效期限設為 60 至 3,600 秒。OpenAI 會採用以下兩者中較短的期限:

  • 上游身分權杖的剩餘有效時間。
  • 規則中設定的存取權杖有效期限。

縮短有效期限,可縮短政策變更後已簽發權杖仍可使用的時間,但工作負載也必須更頻繁地交換權杖。除非工作負載需要不同的取捨,否則可先將有效期限設為 10 分鐘。

防止重放

提供者層級的重放防護使用 JWT 的 jti 宣告。當管理員啟用防止判斷提示重放,且權杖包含非空的 jti 時,在判斷提示到期前,OpenAI 對該提供者只會接受該 jti 一次。

每次交換權杖前,工作負載都必須取得帶有全新 jti 的新判斷提示。如果無法確定上一次交換的結果,重試前也必須這麼做。不含 jti 的判斷提示仍可使用,但不受重放防護。若 jti 為空字串、null 或非字串值,驗證就會失敗。

變更、停用與封存

對身分檢查、授權範圍或權杖有效期限的一般修改,會套用至後續的權杖交換。修改前簽發的存取權杖可能會持續有效,直到原有的存留時間(TTL)結束。

停用規則或提供者會阻止新的權杖交換,並撤銷透過該規則或提供者簽發的 OpenAI 存取權杖。封存的效果相同,且無法復原。若變更提供者的信任設定,例如簽發者或 JWKS 設定,系統會在新設定生效前撤銷已簽發的權杖。

如果需要緊急停止或暫時中斷存取,請停用規則或提供者。只有在確定不再需要該資源時才將其封存。

限制

資源 限制
每個組織中尚未封存的提供者數量 50
每個提供者下尚未封存的規則數量 50
每條規則可精確比對的宣告數量 32
每條規則接受的對象數量 32 個不重複的值
主旨長度 4,096 位元組
精確比對用的宣告對應表或 CEL 條件 16 KiB
存取權杖有效期限 60 至 3,600 秒

如果不同的信任邊界需要各自管理簽發者、金鑰、重放防護或生命週期,請分別建立提供者。如果多個工作負載共用信任設定,但需要不同的主體或存取政策,請在同一個提供者下分別建立規則。