工作負載身分聯合

工作負載身分聯合讓受信任的工作負載使用既有身分，無須儲存 OpenAI API 金鑰或 ChatGPT 認證資訊。工作負載提供由身分提供者核發的短效 Token，OpenAI 再將其交換為短效 OpenAI 存取 Token。

OpenAI API 工作負載也可以透過 X.509 工作負載身分聯合，使用已驗證的憑證身分進行交換。

你可以在 OpenAI API 或 Codex 中使用工作負載身分聯合：

這兩種方式採用相同的信任模型，但管理方式與執行階段組態不同。請先閱讀下方的共通概念與身分提供者指南，再依照工作負載使用的產品，閱讀對應章節。

• OpenAI API： 請繼續閱讀在 OpenAI API 中 使用工作負載身分。
• Codex： 請依照在 Codex 中 使用工作負載身分的說明，完成管理入口網站與 執行階段的設定。

管理員也可以使用管理 API 管理 Codex 提供者與規則。如需了解 規則與生命週期的行為，請參閱Codex 聯合規則 參考資料。

運作方式

工作負載連線前，管理員須先設定以下三個項目：

1. 身分提供者 告知 OpenAI 應信任哪個外部核發者，以及 如何驗證其簽署的 Token 或憑證身分。
2. 存取規則 定義 OpenAI 接受哪些 Token 屬性，以及 工作負載可以使用哪個 OpenAI 身分執行操作。在 OpenAI API 組態中，這稱為 服務帳戶對應；在 Codex 組態中，則稱為聯合規則。
3. OpenAI 主體 會取得最終的存取權。對 OpenAI API 而言， 主體是平台服務帳戶；對 Codex 而言，主體則是 受管理工作區中的 ChatGPT 使用者或服務帳戶。

執行階段的流程如下：

1. 工作負載取得短效 OIDC JWT 或 SPIFFE JWT-SVID；若為 OpenAI API 工作負載，也可以提供 X.509 憑證。
2. 工作負載提供其外部身分，以及所用產品要求的 ID。
3. OpenAI 驗證 Token 或憑證，然後評估已設定的對應或規則。
4. OpenAI 傳回對應主體的短效存取 Token。

Token 交換絕不會建立主體、專案或工作區成員資格。管理員須在設定時建立或選取這些資源。

取得身分 Token

請依照工作負載執行的環境，選擇對應指南：

OpenAI 在文件所述的組態中支援與 OIDC 相容的 JWT 主體 Token， 包括 SPIFFE JWT-SVID。若使用 OpenAI API，且你的 OIDC 提供者未列於其中， 請聯絡 OpenAI 支援團隊。若使用 Codex，請在 OpenAI 管理入口網站中 選擇 自訂 OIDC 。

每份 OIDC 提供者指南都說明如何核發及檢查 Token。若使用 Codex， 請只執行其中的 Token 核發步驟，然後返回 在 Codex 中使用工作負載身分。 這些指南中的 OpenAI 設定與 SDK 範例適用於 OpenAI API 方式。 X.509 聯合僅支援 OpenAI API 方式。

在 OpenAI API 中使用工作負載身分

如果工作負載會直接呼叫 OpenAI API，請使用此方式。你需要具備管理組織工作負載身分提供者與服務帳戶對應的權限。

前往組織設定 > 安全性 > 工作負載身分提供者。 先建立提供者，再從提供者詳細資料頁面 設定其服務帳戶對應。

X.509 提供者

X.509 提供者會從用戶端憑證衍生工作負載身分屬性，而 OpenAI 會依據組織現有的雙向 TLS 組態驗證該憑證。提供者不會儲存憑證，也不會維護獨立的信任存放區。

建立提供者之前，請先前往組織設定 > 安全性 > 雙向 TLS， 設定並啟用作為用戶端憑證信任錨點的受信任憑證。 雙向 TLS 指南說明了權限、 憑證要求、啟用範圍、mTLS 主機、 憑證鏈行為、CEL 篩選器與輪替。

接著，建立 X.509 提供者，衍生一個非空的 openai.subject 值，並將該身分對應至僅具備工作負載所需權限的專案服務帳戶。工作負載向 X.509 Token 端點提供其憑證，以取得短效持有人 Token，然後將持有人 Token 與受接受的用戶端憑證傳送至 API mTLS 端點。

請依照X.509 憑證設定指南，完成儀表板設定與請求的完整流程。

設定 OIDC 工作負載身分提供者

為每個您信任的外部簽發者建立工作負載身分提供者。OpenAI API 工作負載身分支援 OIDC JWT 主體 Token。其組態包括：

自訂 OIDC 探索與已上傳的 JWKS 無法同時使用。啟用自訂探索後，已上傳的 JWKS 選項會隱藏。自訂探索 URL 必須使用公開的 HTTPS，且不得包含憑證、自訂連接埠、查詢字串或片段識別碼。

如果儀表板未顯示 使用自訂 URL 進行 OIDC 探索 ，請使用 標準 OIDC 探索，或改為啟用 使用已上傳的 JWKS 驗證 Token。 請使用身分提供者發布的公開 JWKS， 並在提供者輪替簽署金鑰時更新 JWKS。

當 Token 簽發者與探索主機不同時，請將 OIDC 簽發者 URL 設為 Token 的 iss 宣告，並將 自訂 OIDC 探索 URL 設為 發布提供者探索文件的主機。OpenAI 仍會根據 設定的簽發者檢查 Token；自訂 URL 只決定擷取探索 中繼資料和公開簽署金鑰的位置。

使用 CEL 轉換 Token 宣告

屬性轉換使用 Common Expression Language (CEL)。 OpenAI 支援 langdef.md 中定義的標準 CEL 運算子， 未新增自訂的工作負載身分聯合函式。每個運算式 都會接收一個根物件：

• assertion：已驗證的 JWT 宣告集。

儀表板會自動加上 openai. 前置詞。請輸入 後綴（例如 subject）和運算式（例如 assertion.sub）。API 會將衍生屬性儲存為 openai.subject。

12345678910[
  {
    "attribute": "openai.subject",
    "expression": "assertion.sub"
  },
  {
    "attribute": "openai.repository",
    "expression": "assertion.repository"
  }
]

請使用 CEL 語言規格定義的 CEL 語法。例如，您可以 使用 assertion.sub 或 assertion.repository 等運算式讀取宣告值。不支援的語法或函式 會導致對應解析失敗。

12345678910[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  },
  {
    "attribute": "openai.production",
    "expression": "assertion.ref == \"refs/heads/main\""
  }
]

轉換結果必須是純量值：字串、true 或 false 值、整數或有限數值。陣列、物件、null 值及 求值錯誤都會導致對應解析失敗。OpenAI 會將純量 轉換結果轉為字串，再與對應值比較。 例如，true 會變成 "true"，而 7 會變成 "7"。

以 openai. 開頭的對應鍵只能從屬性轉換 取得值。原始主體 Token 宣告即使已使用 openai. 前置詞， 也不會影響對應判斷，除非您設定了相應的轉換。

管理 JWKS 與金鑰輪替

OpenAI 會使用工作負載身分提供者中設定的金鑰來源，驗證 OIDC 主體 Token：

• OIDC 探索： OpenAI 會擷取簽發者的 /.well-known/openid-configuration，然後擷取探索所得的 jwks_uri。 OpenAI 會將探索文件和遠端 JWKS 酬載快取 600 秒。
• 自訂 OIDC 探索： OpenAI 會從設定的自訂探索基底 URL 擷取 /.well-known/openid-configuration， 然後擷取探索所得的 jwks_uri。Token 的 iss 宣告 仍須符合 OIDC 簽發者 URL。
• 找不到金鑰時重新整理： 如果快取的 JWKS 中找不到 Token 的 kid， OpenAI 會先重新整理 JWKS 並再次查找， 仍找不到才會拒絕該 Token。
• 已上傳的 JWKS： 啟用 使用已上傳的 JWKS 驗證 Token 後， OpenAI 會使用已上傳並儲存於提供者中的 JWKS， 不會執行 OIDC 探索或擷取遠端 JWKS。提供者的更新 可供 Token 交換使用後，新的交換就會使用已儲存的 JWKS。
• 金鑰集： 一個 JWKS 可以包含多把公開金鑰。每把金鑰都必須具有 唯一且非空的 kid。

輪替簽署金鑰時，請在輪替期間於簽發者的 JWKS 中同時發布新舊公開金鑰。這樣可讓舊金鑰簽署的 Token 繼續使用，同時讓 OpenAI 接受新金鑰簽署的 Token。若使用已上傳的 JWKS， 請先更新提供者，再簽發含有新 kid 的 Token； 若簽署 Token 的金鑰不在設定的 JWKS 中，OpenAI 就會拒絕該 Token。

設定服務帳戶對應

服務帳戶對應定義哪些外部身分可以為 OpenAI 服務帳戶產生存取權杖。

對於 X.509 提供者，對應鍵使用衍生的 openai.* 屬性。建議採用 精確的 openai.subject 對應。sub、aud 和 iss 等原始 JWT 宣告 僅適用於 OIDC 提供者。

其組態包括：

屬性值必須是 JSON 純量值。字串值可以在結尾使用一個 萬用字元，但前綴不得為空，例如 repo:example/*。不支援單獨使用萬用字元， 也不支援將萬用字元放在值的中間。

有效的萬用字元值：

• repo:openai/*
• repository:my-org/*

不支援的萬用字元值：

• *
• repo:*:prod
• repo/*/main

儀表板將對應限制顯示為 權限。Token 交換 回應會在 scope 屬性中 以 OAuth 範圍呈現相同限制。對應不能包含管理 API 範圍， 且一般的下游 API 授權規則仍然適用。

對應解析範例

OpenAI 驗證外部身分後，才會開始解析對應。 OpenAI 會查找所要求的 identity_provider_id 和 service_account_id 的對應，略過未啟用的對應，並且只評估 各個對應所需的屬性。只有在恰好一個已啟用的對應 符合所有設定的屬性時，才會核發 Token。

假設 GitHub Actions Token 包含下列宣告：

1234567{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "repository": "my-org/my-repo",
  "ref": "refs/heads/main"
}

提供者可以衍生出一個屬性：

123456[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  }
]

接著，服務帳戶對應便可要求同時符合原始屬性與衍生屬性：

這三個值都必須相符。sub 值使用結尾萬用字元，因此 會與任何以 repo:my-org/my-repo: 為前綴的值相符。 openai.repository_ref 鍵的值來自屬性轉換， 而非 Token 中同名的原始宣告。

如果有多個已啟用的對應符合某次交換，OpenAI 就會拒絕該交換。 OpenAI 要求每組 (provider, service account) 只能有一個相符的對應， 且不會合併不同對應的權限。

連接工作負載

請使用身分提供者指南中的 SDK 範例， 或直接呼叫 Token 交換端點。如需瞭解請求與回應欄位、 授權行為及目前的限制，請參閱 工作負載身分 Token 交換參考資料。

換發存取 Token

如果您直接管理 Token 交換，從 Token 服務將憑證傳遞至應用程式時， 請一併傳遞 access_token 和 expires_at。 expires_at 欄位是以 UTC 表示的絕對到期時間， 格式為以秒為單位的 Unix 時間戳記。請安排在到期前換發 Token， 並預留時間以因應時鐘差異和請求延遲。

expires_in 欄位表示 Token 自核發起算的有效期間，以秒為單位。 例如，在 12:00 UTC 核發且 expires_in: 3600 的 Token 會在 13:00 UTC 到期， 即使另一項服務在 12:05 UTC 才收到該 Token，也不會改變到期時間。 傳輸和處理所花費的時間不會延長 Token 的有效期間。詳情請參閱回應 欄位。

Token 交換不會傳回重新整理 Token。如需換發，請使用有效的外部身分 Token 或用戶端憑證 再次進行交換。

在 Codex 中使用工作負載身分

若要在受管理的 ChatGPT 工作區中執行受信任的 Codex 自動化，請使用此方式。 Codex 會將工作負載對應至 ChatGPT 使用者或服務帳戶， 而非 API 平台的服務帳戶。

如需完整的管理員與執行階段操作程序，請參閱在 Codex 中使用 工作負載身分。 內容涵蓋各提供者的 Token 來源、聯合規則、 必要的 Token 檔案組態、憑證優先順序、支援的 Codex 介面、輪替與驗證。若要選擇性地提供稽核歸屬資訊，Codex 接受 OPENAI_WORKLOAD_IDENTITY_CONTEXT；Codex 指南定義了其結構描述、 隱私限制及稽核行為。

使用管理 API，以程式方式管理 Codex 提供者與規則。聯合規則 參考資料 說明如何讓單一規則接受多個外部主體，並將這些主體對應至同一個 ChatGPT 主體。

排解連線問題

OpenAI 拒絕身分 Token

在本機解碼 Token，並將其 iss、aud、sub、exp、iat 及 提供者專屬宣告，與提供者的組態進行比對。請勿將正式環境的 Token 貼到第三方 JWT 工具中。

如果使用 OpenAI API，也請將 Token 屬性與所選的服務帳戶對應進行比對。 如果使用 Codex，則請將這些屬性與所選的聯合規則進行比對。

OpenAI API 對應不相符

確認請求使用的是預期的身分提供者與服務帳戶 ID， 且對應已啟用，並且恰好只有一個對應相符。 請參閱Token 交換錯誤參考資料， 瞭解詳細的錯誤類別。

Codex 回報組態不完整

確認 Codex 程序具有兩個必要的工作負載身分環境變數， 且 OPENAI_IDENTITY_TOKEN_FILE 包含指向 目前有效 Token 的絕對路徑。請檢查檔案及其父目錄的權限。

Codex 使用了其他憑證

將兩個必要的工作負載身分變數載入 Codex 程序。 只要其中任一變數存在，就會優先選用 WIF，而非 API 金鑰、存取權杖及 已儲存的登入資訊。請啟動新程序並載入下載的組態， 然後再次執行 codex login status。

安全性建議

• 為每個應用程式或工作負載使用專用主體。
• 將正式環境與非正式環境分開。
• 優先使用精確的宣告比對，避免使用範圍過廣的模式。
• 僅授予工作負載所需的存取權。
• 為存取權杖設定較短的有效期限。
• 審查並移除未使用的提供者、對應及規則。
• 審查 Token 交換錯誤及非預期的存取模式。

相關文件

• 在 Codex 中使用工作負載身分
• Codex 聯合規則參考資料
• 使用管理 API 管理 Codex 工作負載身分
• 工作負載身分 Token 交換參考資料
• Codex 身分驗證
• Codex 環境變數
• Codex 非互動模式