雙向 TLS

雙向 TLS (mTLS) 為 OpenAI API 請求加入 TLS 用戶端憑證驗證。為組織或專案啟用受信任的憑證後，該範圍內的請求除了原本的 Bearer 認證資訊外，還必須提供可接受的用戶端憑證。

如果工作負載能安全地保管用戶端私密金鑰，而你希望 OpenAI 在授權 API 請求前先驗證其憑證身分，就可以使用 mTLS。mTLS 不會取代 API 金鑰、服務帳戶認證資訊或工作負載身分存取權杖。

設定 mTLS 前的準備事項

任何 API 組織都可以透過一般的角色型存取控制 (RBAC) 管理 mTLS：

• api.mtls.read 允許主體列出、檢視及測試憑證設定。
• api.mtls.write 允許主體上傳、更新、啟用、停用及 刪除憑證。

組織擁有者角色包含這些權限，你也可以 透過自訂角色授予這些權限。如需詳細資訊，請參閱管理 OpenAI 平台的 權限。

請準備：

• 每個工作負載各自的用戶端憑證及其私密金鑰。
• 建立從用戶端憑證到信任錨點之路徑所需的所有中繼憑證。
• 可在組織或專案層級啟用、採用 PEM 編碼的穩定信任錨點。
• 在為正式環境流量啟用 mTLS 前，準備一個非關鍵專案，以及經過測試的復原方式。

請勿將私密金鑰納入原始碼版本控制。請勿在日誌中記錄私密金鑰、憑證內容或 Bearer 認證資訊。

上傳並啟用信任憑證

上傳只會儲存憑證，不會強制執行 mTLS。啟用憑證才會改變請求的處理行為。

1. 開啟組織設定 > 安全性 > 雙向 TLS。
2. 每個憑證物件請上傳一個 PEM 編碼的信任錨點，並為其命名，讓名稱能識別憑證授權單位及輪替代次。
3. 你可以選擇新增 CEL 篩選器， 限制該錨點可接受哪些已通過驗證的用戶端憑證。
4. 先為非關鍵專案啟用憑證。 從每個預期使用的工作負載，透過 mTLS API 主機 傳送具代表性的請求。
5. 驗證成功後，再為其他專案或組織啟用憑證。

你也可以透過 API 管理憑證：

請使用具備所需 api.mtls.read 或 api.mtls.write 權限的 認證資訊。如需請求與回應的結構描述，請參閱組織憑證 API 參考文件。

憑證要求

每個憑證物件請使用一個 PEM 編碼的信任錨點。上傳內容必須包含有效憑證，且該憑證在上傳後的剩餘有效期必須超過一天。用戶端憑證必須包含授權單位金鑰識別碼 (AKI)，以供請求驗證使用。

請求若要通過 mTLS，必須符合以下條件：

• 用戶端憑證在發出請求時必須有效，且適用於 TLS 用戶端身分驗證。
• 用戶端憑證必須能建立通往組織或專案層級已啟用信任錨點的有效路徑。
• 如果路徑包含中繼憑證，用戶端必須在 TLS 交握期間提供這些憑證。
• 設定的信任錨點與用戶端憑證鏈必須通過標準 X.509 用戶端憑證路徑驗證。

如果上傳內容包含多個 PEM 編碼的憑證，請求憑證鏈驗證只會使用第一個設定的憑證作為錨點；請勿依賴 PEM 憑證套件的語意。

OpenAI 不會從授權單位資訊存取 (AIA) URL 擷取缺少的中繼憑證，也不會執行憑證撤銷清單 (CRL) 或線上憑證狀態通訊協定 (OCSP) 檢查。請提供所需的完整憑證鏈，並透過憑證輪替、停用及你自己的憑證生命週期控制措施來因應事件。

瞭解驗證順序

OpenAI 會先檢查專案層級已啟用的憑證，再檢查組織層級已啟用的憑證。如果這兩個範圍都沒有已啟用的憑證，mTLS 就不會對請求額外進行憑證檢查。

存在已啟用的憑證時，OpenAI 會依照以下順序驗證用戶端身分：

1. OpenAI 會先嘗試既有的直接路徑，直接以已啟用的錨點驗證用戶端憑證，不使用請求中的中繼憑證。
2. 直接路徑出現一般的無符合項目結果後，OpenAI 會使用 TLS 連線提供的用戶端憑證與中繼憑證，嘗試進行請求憑證鏈驗證。
3. 如果路徑通過驗證，且已啟用的憑證設有 CEL 篩選器，OpenAI 就會以該篩選器檢查已通過驗證的用戶端憑證。

預設即可使用請求憑證鏈驗證。

請求憑證鏈路徑是在一般無符合項目情況下使用的備援方式，並非所有直接路徑錯誤的復原方式。如果憑證資料缺失或格式錯誤、缺少 AKI，或直接路徑選定錨點後發生確定性錯誤，請求可能會直接失敗，而不會嘗試驗證所提供的憑證鏈。

使用 CEL 篩選用戶端憑證

你可以選擇為已上傳的憑證附加通用運算式語言 (CEL) 篩選器，以限制該錨點可接受哪些已通過驗證的用戶端憑證。運算式的求值結果必須是布林值，且不論使用直接路徑或請求憑證鏈路徑，都會針對已通過驗證的用戶端憑證執行。

CEL 提供以下欄位：

• subject.common_name、subject.country_code、subject.organization、 subject.organizational_unit、subject.locality、subject.province、 subject.street_address 及 subject.postal_code。
• subject_alt_names 是一個清單，每個項目都提供 type、value 及 oid。 支援的 SAN 類型識別碼為 DNS、EMAIL、IP_ADDRESS、URI 及 CUSTOM。

例如，要求組織單位為正式環境，且 DNS SAN 位於特定命名空間：

subject.organizational_unit == "Production" &&
subject_alt_names.exists(san, san.type == DNS && san.value.endsWith(".example.com"))

如果憑證通過驗證，但不符合篩選器條件，請求就會失敗，並傳回 certificate_attribute_verification_failed。儲存原則時，OpenAI 會拒絕未通過驗證的原則。

使用 mTLS 主機

將 API 流量傳送至 mTLS 主機，而非 api.openai.com：

mTLS 以主機為基礎。請使用您在對應 API 介面上呼叫的相同 /v1 路由， 並測試工作負載使用的每個 API 和模型。 不同區域主機可用的路由和模型可能有所不同。

例如，將一般持有者認證資訊和用戶端憑證傳送至預設 mTLS 主機：

1234567export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"

curl https://mtls.api.openai.com/v1/models \
  --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --header "Authorization: Bearer $OPENAI_API_KEY"

憑證鏈檔案應先放置用戶端憑證，後面再接上所有必要的中繼憑證。請勿在 HTTP 標頭或請求本文中傳送憑證資料。

X.509 工作負載身分聯合使用獨立且固定的交換端點： POST https://mtls.auth.openai.com/oauth/token。此交換會產生 短效持有者 Token；不提供僅憑憑證進行的 API 身分驗證。 如需完整的請求格式，請參閱工作負載身分 Token 交換 參考資料。

輪替憑證

輪替信任錨點時，請讓新舊錨點保持一段重疊啟用期，讓現有工作負載持續運作：

1. 上傳新的信任錨點，同時保持舊錨點啟用。
2. 在每個預定使用的專案中，或在組織層級啟用新錨點。
3. 更新工作負載，讓它們提供可透過憑證鏈連至新錨點的用戶端憑證，然後測試它們使用的每個 mTLS 主機和 API 介面。
4. 所有工作負載都完成移轉後，再停用舊錨點。
5. 必須先在組織及所有專案中停用舊憑證，才能將其刪除。

您可以輪替中繼憑證，而不必變更已設定的信任錨點。請在後續請求中提供新的完整憑證鏈。

排解請求問題

使用穩定的錯誤代碼，區分組態錯誤與暫時性服務錯誤：

對於管理請求，mtls_certificate_invalid 表示上傳的 PEM 未通過驗證； expired_certificate 表示憑證即將到期或已過期； mtls_cel_policy_invalid 表示篩選條件未通過驗證； certificate_in_use 表示您必須先停用憑證， 才能將其刪除。

目前的限制

• 每個組織最多可上傳 50 個憑證物件。
• mTLS 在一般 API 身分驗證之外增加憑證驗證；不提供僅憑憑證進行的 API 授權。
• OpenAI 不會透過 AIA 擷取中繼憑證，也不會執行 CRL 或 OCSP 檢查。
• Private Link 與 mTLS 不相容。如果您需要改用私人 Azure 網路路徑， 請參閱 Private Link。
• 支援的 API mTLS 主機為 mtls.api.openai.com、 mtls-us.api.openai.com 和 mtls-eu.api.openai.com。請勿假設 其他每個區域 API 主機都有對應的 mTLS 主機。
• X.509 工作負載身分聯合不會傳回重新整理 Token， 也不會使用 DPoP、cnf 宣告或與憑證繫結的持有者 Token。請參閱 使用 X.509 憑證 設定工作負載身分聯合。