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

工作負載身分同盟

驗證 OpenAI API 和 Codex 工作負載的身分,無須儲存長效認證資料。

工作負載身分同盟讓受信任的工作負載使用既有身分,無須儲存 OpenAI API 金鑰或 ChatGPT 認證資料。工作負載提交由身分提供者簽發的短效權杖,再由 OpenAI 將其換成短效的 OpenAI 存取權杖。

OpenAI API 工作負載也可以透過 X.509 工作負載身分同盟,以經過驗證的憑證身分換取存取權杖。

OpenAI API 和 Codex 都支援工作負載身分同盟:

OpenAI API Codex
OpenAI 身分 API 平台專案中的服務帳戶 受管理 ChatGPT 工作區中的使用者或服務帳戶
管理員設定的位置 OpenAI 平台 OpenAI 管理入口網站
工作負載的連線方式 OpenAI SDK 或權杖交換端點 Codex 環境變數和身分權杖檔案
存取權杖的適用範圍 對應服務帳戶可使用的 API 和權限 對應工作區主體擁有的 Codex 存取權

兩者採用相同的信任模型,但管理方式和執行階段設定有所不同。請先閱讀下方的共通概念和身分提供者指南,再依工作負載使用的產品,按照對應章節進行設定。

如需瞭解規則的運作方式與生命週期,請參閱 Codex 同盟規則參考文件。

運作方式

工作負載連線前,管理員須設定三個項目:

  1. 身分提供者指定 OpenAI 應信任哪個外部簽發者,以及如何驗證該簽發者簽署的權杖或憑證身分。
  2. 存取規則指定 OpenAI 接受哪些權杖屬性,以及工作負載可以使用哪個 OpenAI 身分執行操作。在 OpenAI API 設定中,這稱為服務帳戶對應;在 Codex 設定中,則稱為同盟規則。
  3. OpenAI 主體取得對應的存取權。對 OpenAI API 而言,主體是 API 平台的服務帳戶;對 Codex 而言,主體是受管理工作區中的 ChatGPT 使用者或服務帳戶。

執行時的流程如下:

  1. 工作負載取得短效的 OIDC JWT 或 SPIFFE JWT-SVID。OpenAI API 工作負載也可以提交 X.509 憑證。
  2. 工作負載提交外部身分,以及所用產品要求的識別碼。
  3. OpenAI 驗證權杖或憑證,再評估已設定的對應或規則。
  4. OpenAI 傳回對應主體的短效存取權杖。

權杖交換不會建立主體或專案,也不會將主體加入工作區。這些資源由管理員在設定時建立或選取。

取得身分權杖

請依工作負載的執行環境選擇指南:

在文件所述的設定下,OpenAI 支援與 OIDC 相容的 JWT 主體權杖,包括 SPIFFE JWT-SVID。如果你使用 OpenAI API,而上方未列出你的 OIDC 提供者,請聯絡 OpenAI 支援團隊。如果你使用 Codex,請在 OpenAI 管理入口網站中選擇自訂 OIDC。

每份 OIDC 提供者指南都說明了如何簽發和檢查權杖。若使用 Codex,只需完成簽發權杖的步驟,再回到搭配 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 權杖端點提交憑證,以取得短效的持有人權杖,再將該權杖與端點接受的用戶端憑證一併傳送至 API mTLS 端點。

如需瞭解在控制台中設定及傳送請求的完整流程,請參閱 X.509 憑證設定指南。

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

為每個受信任的外部簽發者建立一個工作負載身分提供者。OpenAI API 的工作負載身分功能支援 OIDC JWT 主體權杖。設定項目如下:

選項 說明
名稱 工作負載身分提供者在組織內的唯一名稱。
OIDC 簽發者 URL 預期的 OIDC 簽發者 URL。比對簽發者時會忽略結尾的斜線。
對象 外部主體權杖中 aud 宣告的預期值。
說明 工作負載身分提供者的說明,可省略。
使用自訂 URL 進行 OIDC 探索 啟用後,OpenAI 會從公開的 HTTPS URL 擷取 OIDC 探索中繼資料。此 URL 可以與權杖簽發者的 URL 不同。
自訂 OIDC 探索 URL 啟用自訂探索時使用的探索基底 URL,或完整的 /.well-known/openid-configuration URL。
使用上傳的 JWKS 驗證權杖 啟用後,OpenAI 會使用上傳的 JWKS 驗證權杖,無須透過 OIDC 探索擷取金鑰。
JWKS JSON 啟用上傳 JWKS 驗證功能時使用的公開 JWKS 物件。上傳的 JWKS 必須包含非空的 keys 陣列,且不得包含任何私密金鑰資料。
屬性轉換 選用的 CEL 運算式,可根據權杖宣告衍生自訂的 openai.* 屬性,供判斷對應是否相符。

自訂 OIDC 探索與上傳 JWKS 兩種方式只能擇一使用。啟用自訂探索後,控制台會隱藏上傳 JWKS 的選項。自訂探索 URL 必須是公開的 HTTPS 網址,且不得包含認證資料、自訂連接埠、查詢字串或片段識別碼。

如果控制台未顯示使用自訂 URL 進行 OIDC 探索,請使用標準 OIDC 探索,或啟用使用上傳的 JWKS 驗證權杖。請使用身分提供者發布的公開 JWKS,並在提供者輪替簽署金鑰時更新 JWKS。

如果權杖簽發者和探索主機不同,請將 OIDC 簽發者 URL 設為權杖的 iss 宣告值,並將自訂 OIDC 探索 URL 設為發布提供者探索文件的主機網址。OpenAI 仍會依照設定的簽發者檢查權杖;自訂 URL 僅決定 OpenAI 從哪裡擷取探索中繼資料和公開簽署金鑰。

使用 CEL 轉換權杖宣告

屬性轉換使用通用運算式語言(CEL)。OpenAI 支援 langdef.md 中定義的標準 CEL 運算子,未另外提供工作負載身分同盟專用的函式。每個運算式都會收到一個根物件:

  • assertion:通過驗證的 JWT 宣告集合。

控制台會自動加上 openai. 前置字串。請輸入後綴(例如 subject)和運算式(例如 assertion.sub)。在此範例中,API 會將衍生屬性儲存為 openai.subject。

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

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

[
  {
    "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. 開頭的對應鍵只能透過屬性轉換解析。即使主體權杖的原始宣告帶有 openai. 前置字串,也必須設定相應的轉換,該宣告才會影響對應結果。

管理 JWKS 與金鑰輪替

OpenAI 會使用工作負載身分提供者中設定的金鑰來源,驗證 OIDC 主體權杖:

  • OIDC 探索: OpenAI 先擷取簽發者的 /.well-known/openid-configuration,再從文件指定的 jwks_uri 擷取金鑰集。OpenAI 會將探索文件和遠端 JWKS 內容快取 600 秒。
  • 自訂 OIDC 探索: OpenAI 會從設定的自訂探索基底 URL 擷取 /.well-known/openid-configuration,再從文件指定的 jwks_uri 擷取金鑰集。權杖的 iss 宣告仍須與 OIDC 簽發者 URL 相符。
  • 找不到金鑰時重新整理: 如果快取的 JWKS 中沒有權杖的 kid,OpenAI 會先重新整理 JWKS 並再次查找,仍找不到才會拒絕權杖。
  • 已上傳的 JWKS: 啟用使用上傳的 JWKS 驗證權杖後,OpenAI 會使用已上傳並儲存於提供者設定中的 JWKS,不會執行 OIDC 探索或擷取遠端 JWKS。提供者的更新對權杖交換生效後,新的交換請求就會使用已儲存的 JWKS。
  • 金鑰集: 一個 JWKS 可包含多把公開金鑰。每把金鑰都必須有唯一且非空的 kid。

輪替簽署金鑰時,請在整個輪替期間將新舊公開金鑰一併發布於簽發者的 JWKS 中。如此一來,OpenAI 就能接受以新金鑰簽署的權杖,而以舊金鑰簽署的權杖也能繼續使用。如果使用上傳的 JWKS,請先更新提供者設定,再簽發帶有新 kid 的權杖。若設定的 JWKS 中沒有對應金鑰,OpenAI 就會拒絕以該金鑰簽署的權杖。

設定服務帳戶對應

服務帳戶對應指定哪些外部身分可以取得特定 OpenAI 服務帳戶的存取權杖。

對於 X.509 提供者,對應鍵使用衍生的 openai.* 屬性。建議優先使用要求 openai.subject 完全相符的對應。sub、aud 和 iss 等原始 JWT 宣告僅適用於 OIDC 提供者。

設定項目如下:

選項 說明
名稱 此對應在工作負載身分提供者內的唯一名稱。
鍵 要比對的屬性鍵。可使用原始權杖宣告(例如 sub、aud 或 iss),或衍生屬性(例如 openai.subject)。
值 屬性必須與此值相符,OpenAI 才會簽發權杖。
說明 此對應的說明,可省略。
專案 目標服務帳戶所屬的專案。
服務帳戶 工作負載可以使用的服務帳戶。你可以在選取的專案中建立新的服務帳戶,或選取現有的服務帳戶。
權限 選用的 API 權限,可進一步限制透過此對應簽發的存取權杖。這些權限不能授予超出對應服務帳戶權限範圍的存取權。

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

有效的萬用字元值:

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

不支援的萬用字元值:

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

控制台會在權限中顯示對應的限制。權杖交換回應會在 scope 屬性中,以 OAuth 範圍列出相同的限制。對應不能包含管理 API 的範圍,下游 API 仍會照常執行授權檢查。

對應解析範例

OpenAI 驗證外部身分後,才會開始解析對應。OpenAI 會根據請求中的 identity_provider_id 和 service_account_id 查找對應,略過未啟用的對應,並僅評估每個對應所需的屬性。只有在恰好一個已啟用的對應符合所有已設定的屬性條件時,OpenAI 才會簽發權杖。

假設 GitHub Actions 權杖包含以下宣告:

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

提供者可以衍生以下屬性:

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

服務帳戶對應便可要求原始屬性和衍生屬性同時符合下列條件:

鍵 值
iss https://token.actions.githubusercontent.com
sub repo:my-org/my-repo:*
openai.repository_ref my-org/my-repo@refs/heads/main

這三個值都必須相符。sub 的設定值以萬用字元結尾,因此任何以 repo:my-org/my-repo: 開頭的值都符合條件。openai.repository_ref 鍵的值取自屬性轉換,而非權杖中的同名原始宣告。

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

連線工作負載

請使用身分提供者指南中的 SDK 範例,或直接呼叫權杖交換端點。如需瞭解請求和回應欄位、授權方式及目前的限制,請參閱工作負載身分權杖交換參考文件。

更新存取權杖

如果你自行管理權杖交換,從權杖服務向應用程式傳遞認證資料時,請一併傳遞 access_token 和 expires_at。expires_at 欄位是以秒為單位的 Unix 時間戳記,表示權杖到期的確切 UTC 時間。請安排在到期前更新權杖,並為時鐘誤差和請求延遲預留時間。

expires_in 欄位表示從簽發時起算的權杖有效秒數。例如,若權杖於 UTC 12:00 簽發,且 expires_in: 3600,權杖就會在 UTC 13:00 到期,即使另一個服務於 UTC 12:05 才收到權杖也是如此。傳輸和處理時間不會延長權杖的有效期限。詳情請參閱回應欄位。

權杖交換不會傳回重新整理權杖。若要更新存取權杖,請使用有效的外部身分權杖或用戶端憑證再次進行交換。

搭配 Codex 使用工作負載身分

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

Codex 工作負載身分同盟目前處於 Beta 測試階段,必須先為你的工作區啟用此功能才能使用。如需申請存取權,請聯絡你的 OpenAI 代表或 OpenAI 支援團隊。

同盟規則參考文件說明如何使用單一規則接受多個外部主體,並將它們對應至同一個 ChatGPT 主體。

排解連線問題

OpenAI 拒絕身分權杖

請在本機解碼權杖,並將其中的 iss、aud、sub、exp、iat 和提供者專屬宣告與提供者設定比對。請勿將正式環境的權杖貼到第三方 JWT 工具中。

若使用 OpenAI API,還要將權杖屬性與選取的服務帳戶對應比對。若使用 Codex,則要與選取的同盟規則比對。

找不到相符的 OpenAI API 對應

確認請求使用的是預期的身分提供者識別碼和服務帳戶識別碼,對應已啟用,且恰好有一個對應相符。如需瞭解詳細的錯誤類別,請參閱權杖交換錯誤參考文件。

Codex 回報設定不完整

確認 Codex 程序中已設定兩個必要的工作負載身分環境變數,且 OPENAI_IDENTITY_TOKEN_FILE 的值是指向目前有效權杖檔案的絕對路徑。請檢查檔案及其上層目錄的權限。

Codex 使用了其他認證資料

將兩個必要的工作負載身分環境變數都載入 Codex 程序。只要其中一個變數存在,Codex 就會優先選用工作負載身分同盟(WIF),其優先順序高於 API 金鑰、存取權杖和已儲存的登入資料。啟動新的 Codex 程序時,請載入已下載的設定,再次執行 codex login status。

安全性建議

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

相關文件