使用管理 API 管理 Codex 工作負載身分

使用組織管理 API，透過基礎架構工具或 CI 管理 Codex 工作負載身分提供者與聯合規則。此 API 提供的提供者與規則模型，與 OpenAI 管理入口網站相同。

此 API 在路徑與回應物件中將聯合規則稱為 mappings。 本頁以 聯合規則 表示產品概念，只有在 提及 API 欄位或路徑時才使用 mapping。

先決條件

你需要：

• 已為你的組織及受管理 ChatGPT 工作區啟用工作負載身分聯合。
• 一組管理 API 金鑰， 其擁有者須為具備工作負載身分管理權限的有效管理員。
• 受管理 ChatGPT 工作區的 ID。
• 該工作區中現有且有效的人員帳戶或服務帳戶的 OpenAI 使用者 ID。
• 工作負載的 OIDC Token 或 SPIFFE JWT-SVID 所使用的簽發者、對象及宣告。

WIF 端點使用資源 ID，而非名稱。這些端點不會列出或建立 ChatGPT 工作區或安全性主體。請從你的佈建系統提供這些 ID。如果你未以程式設計方式管理這些資源，請使用 OpenAI 管理入口網站建立或選取安全性主體，並連接該工作負載。

在你的環境中設定管理 API 金鑰：

export OPENAI_ADMIN_KEY="<admin-api-key>"

管理 API 金鑰是長效憑證。請將金鑰儲存在祕密管理工具中，不要提交至程式碼庫，也不要用於 Codex 執行階段的身分驗證。

端點

所有請求均使用 https://api.openai.com，並在 Bearer 授權標頭中提供管理 API 金鑰。

清單回應使用 { "object": "list", "data": [...] }。 這些端點不使用分頁。

建立 OIDC 提供者

針對每個想要獨立管理的簽發者與信任邊界， 各建立一個提供者。將範例中的簽發者與對象替換為 範例 Token 中的確切值。在本機檢查 Token 的 iat 與 exp 宣告，再選擇 可接受的判斷提示存留時間，使其涵蓋簽發者預期的 exp - iat 範圍。 OpenAI 檢查的是完整存留時間，而非 Token 剩餘的有效時間。

使用 Microsoft Entra 時，請勿假設判斷提示的存留時間為一小時。存取權杖的存留時間 各有不同， 而且 Microsoft 不支援設定受控識別 Token 的 存留時間。 請將 MAX_ASSERTION_LIFETIME_SECONDS 替換為經核准的整數，範圍為 1 至 176,400。此提供者限制與聯合規則簽發的 OpenAI 存取權杖 存留時間是分開設定的。

1234567891011121314151617181920212223MAX_ASSERTION_LIFETIME_SECONDS="<accepted-issuer-lifetime-seconds>"

jq -n \
  --argjson max_assertion_lifetime_seconds "$MAX_ASSERTION_LIFETIME_SECONDS" \
  '{
    name: "entra-production",
    type: "oidc",
    issuer: "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0",
    audience: "api://openai-codex-production",
    description: "Production Codex workloads in Microsoft Azure",
    max_assertion_lifetime_seconds: $max_assertion_lifetime_seconds,
    check_jti: true
  }' > provider.json

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/organization/workload_identity/providers \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data @provider.json \
  --output provider-response.json

PROVIDER_ID="$(jq -r .id provider-response.json)"
printf 'Created provider %s\n' "$PROVIDER_ID"

預期輸出以身分提供者 ID 開頭：

Created provider idp_...

OIDC 提供者預設會在其簽發者 URL 進行探索。若公開探索文件位於其他位置，請使用 custom_url； 若要明確指定公開 JWKS URL，請使用 jwks_uri； 若要上傳公開金鑰，請搭配使用 jwks_local: true 與 jwks。 請勿包含私密金鑰資料。

建立 SPIFFE JWT-SVID 提供者

將 type 設為 spiffe_jwt，將 issuer 設為標準信任網域，並 提供公開套件 URL 或上傳的 SPIFFE 套件。SPIFFE 規則 也必須設定 audiences。

12345678{
  "name": "spiffe-production",
  "type": "spiffe_jwt",
  "issuer": "spiffe://example.com",
  "jwks_uri": "https://spiffe.example.com/bundle.json",
  "max_assertion_lifetime_seconds": 3600,
  "check_jti": true
}

若使用上傳的套件，請將 jwks_local 設為 true，以 jwks 物件取代 jwks_uri， 並至少包含一個 use 為 jwt-svid 的公開金鑰。

建立聯合規則

一項規則以一個現有安全性主體為目標，可比對一個或多個外部工作負載身分。此範例接受一個 Azure 受控識別主旨：

1234567891011121314151617181920212223242526export WORKSPACE_ID="<managed-chatgpt-workspace-id>"
export PRINCIPAL_ID="<existing-openai-user-id>"

jq -n \
  --arg workspace_id "$WORKSPACE_ID" \
  --arg principal_id "$PRINCIPAL_ID" \
  '{
    name: "entra-payments-production",
    description: "Production payments workload",
    workspace_id: $workspace_id,
    principal_id: $principal_id,
    external_subject: "11111111-2222-3333-4444-555555555555",
    audiences: ["api://openai-codex-production"],
    access_token_lifetime_seconds: 600,
    enabled: true
  }' > rule.json

curl --fail-with-body --silent --show-error \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID/mappings" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  --data @rule.json \
  --output rule-response.json

FEDERATION_RULE_ID="$(jq -r .id rule-response.json)"
printf 'Created federation rule %s\n' "$FEDERATION_RULE_ID"

預期輸出以對應 ID 開頭。Codex 會將此值用作 OPENAI_FEDERATION_RULE_ID：

Created federation rule idpm_...

若要在一項規則中允許一組主旨，請省略 external_subject，並使用 CEL 條件：

123{
  "condition": "assertion.sub in [\"workload-a\", \"workload-b\"]"
}

至少設定 external_subject、claims 或 condition 其中一項。 所有已設定的身分檢查都必須通過。請參閱聯合規則 參考資料， 瞭解基數、CEL、對象、範圍與存留時間的運作方式。

列出資源並調和其狀態

建立提供者之前，請先列出提供者，讓你的自動化流程能比較預期組態與目前狀態：

123curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/organization/workload_identity/providers \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" | jq .

接著列出提供者底下的規則：

123curl --fail-with-body --silent --show-error \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID/mappings" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" | jq .

此 API 未定義等冪鍵契約。請將傳回的 ID 儲存在經核准的組態狀態中，在變更資源前先讀取其目前狀態，再依 ID 更新。不要每次執行都建立替代資源。

更新或停用資源

更新時使用 POST，且只提供要變更的欄位。此範例會變更 規則的存留時間：

123456curl --fail-with-body --silent --show-error \
  -X POST \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID/mappings/$FEDERATION_RULE_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"access_token_lifetime_seconds": 300}' | jq .

停用規則以立即停止：

123456curl --fail-with-body --silent --show-error \
  -X POST \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID/mappings/$FEDERATION_RULE_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}' | jq .

在提供者路徑上將 enabled 設為 false，即可停止該提供者 底下的所有規則。停用會封鎖新的交換，並撤銷 透過該資源簽發的存取權杖。待其安全性主體、工作區、 繫結與提供者均處於有效狀態後，即可重新啟用。

一般規則編輯只會影響新的交換。編輯前簽發的 Token 可能會持續有效，直到 TTL 到期。變更提供者的信任設定時，會在新信任設定生效前撤銷已簽發的 Token。

封存資源

DELETE 會封存提供者或規則，而非將其抹除。封存會封鎖新的 交換、撤銷已簽發的 Token，並在一般清單結果中隱藏該資源， 且無法復原。

封存規則：

1234curl --fail-with-body --silent --show-error \
  -X DELETE \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID/mappings/$FEDERATION_RULE_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY"

封存提供者：

1234curl --fail-with-body --silent --show-error \
  -X DELETE \
  "https://api.openai.com/v1/organization/workload_identity/providers/$PROVIDER_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY"

封存提供者會撤銷其 Codex 規則的存取權。你必須先移除所有非 Codex 產品的對應，才能封存該提供者。這能保護現有的 OpenAI API 工作負載身分組態。

提供者欄位

建立時必須提供 name 與 issuer。更新時可提供可變更的欄位， 但不包含 type。

探索與明確指定或上傳金鑰，是可擇一使用的驗證模式。 簽發者、探索和 JWKS URL 的驗證要求， 請參閱工作負載身分概覽。

同盟規則欄位

建立時必須提供 workspace_id 和 principal_id，以及至少一項身分檢查。 建立後便無法變更工作區或主體。

提供者回應使用 workload_identity_provider；規則回應使用 workload_identity_mapping。兩者皆包含 id、enabled、created_at 和 updated_at。時間戳記採用以秒為單位的 Unix 時間。

限制與錯誤

一個組織最多可有 50 個未封存的提供者。一個提供者最多可有 50 個未封存的規則。API 會傳回：

• 400：要求欄位、提供者信任設定、規則條件或範圍有誤，或 主體的成員資格未啟用。
• 403：管理 API 金鑰擁有者無法管理工作負載身分。
• 404：組織未與租用戶建立關聯，或所要求的 資源位於組織與租用戶的邊界之外。
• 409：達到提供者或規則數量限制、主旨衝突、繫結未啟用，或 生命週期衝突。

請將 404 視為不揭露資源資訊的回應：服務不會透露 其他組織或租用戶所擁有的提供者或規則。若收到暫時性的 429 和 5xx 回應，請在每次重試前等待，並逐次增加等待時間，但設定上限。 若發生驗證或權限錯誤，請先變更要求或管理員狀態， 再重試。