聯合規則決定哪些通過驗證的工作負載身分可以代表特定的 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 秒 |
如果不同的信任邊界需要各自管理簽發者、金鑰、重放防護或生命週期,請分別建立提供者。如果多個工作負載共用信任設定,但需要不同的主體或存取政策,請在同一個提供者下分別建立規則。