雙向 TLS(mTLS)為 OpenAI API 請求加入 TLS 用戶端憑證驗證。在組織或專案中啟用受信任的憑證後,該範圍內的請求除了原本使用的 Bearer 認證資料,還必須提供可接受的用戶端憑證。
如果工作負載能安全保管用戶端私密金鑰,而且你希望 OpenAI 在授權 API 請求之前先驗證憑證所代表的身分,就可以使用 mTLS。mTLS 無法取代 API 金鑰、服務帳戶認證資料或工作負載身分存取權杖。
X.509 工作負載身分聯合使用相同的已啟用 mTLS 信任錨點。憑證交換會傳回短效 Bearer 權杖,後續 API 呼叫仍須同時傳送該權杖與 API 可接受的 mTLS 憑證。請參閱使用 X.509 憑證設定工作負載身分聯合。
設定 mTLS 前的準備工作
任何 API 組織都可以透過一般的角色型存取控制(RBAC)管理 mTLS:
api.mtls.read允許安全性主體列出、檢視及測試憑證設定。api.mtls.write允許安全性主體上傳、更新、啟用、停用及刪除憑證。
組織擁有者角色具備這些權限,你也可以透過自訂角色授予這些權限。詳情請參閱管理 OpenAI 平台的權限。
請備妥下列項目:
- 每個工作負載的用戶端憑證及其私密金鑰。
- 建立從用戶端憑證到信任錨點的路徑所需的所有中繼憑證。
- 可在組織或專案層級啟用、採用 PEM 編碼的穩定信任錨點。
- 在為正式環境流量啟用 mTLS 之前,先準備一個非關鍵專案,並測試復原方式。
請勿將私密金鑰納入版本控制,也不要將私密金鑰、憑證內容或 Bearer 認證資料寫入日誌。
上傳並啟用信任錨點
上傳憑證只會儲存憑證。啟用憑證後,才會對請求強制執行 mTLS 驗證。
- 開啟組織設定 > 安全性 > 雙向 TLS。
- 為每個憑證物件上傳一個採用 PEM 編碼的信任錨點。命名時,請標明憑證授權單位及輪替代次。
- 視需要加入 CEL 篩選器,限制此錨點可接受哪些已通過驗證的用戶端憑證。
- 先在非關鍵專案中啟用憑證。讓每個預計使用 mTLS 的工作負載透過 mTLS API 主機傳送具代表性的請求。
- 確認測試成功後,再為其他專案或整個組織啟用憑證。
你也可以透過 API 管理憑證:
| 任務 | 端點 |
|---|---|
| 上傳憑證 | POST /v1/organization/certificates |
| 列出組織憑證 | GET /v1/organization/certificates |
| 取得、更新或刪除憑證 | GET、POST 或 DELETE /v1/organization/certificates/{certificate_id} |
| 為組織啟用或停用憑證 | POST /v1/organization/certificates/activate 或 POST /v1/organization/certificates/deactivate |
| 列出、啟用或停用專案憑證 | GET /v1/organization/projects/{project_id}/certificates、POST /v1/organization/projects/{project_id}/certificates/activate 或 POST /v1/organization/projects/{project_id}/certificates/deactivate |
請使用具備所需 api.mtls.read 或 api.mtls.write 權限的認證資料。如需請求與回應的結構描述,請參閱組織憑證 API 參考文件。
憑證要求
每個憑證物件應使用一個採用 PEM 編碼的信任錨點。上傳的憑證必須有效,且上傳時距離到期須超過一天。用戶端憑證必須包含授權單位金鑰識別碼(AKI),才能驗證請求。
請求必須符合下列條件才能通過 mTLS 驗證:
- 發出請求時,用戶端憑證必須有效,且適用於 TLS 用戶端身分驗證。
- 必須能從用戶端憑證建立有效路徑,連至組織或專案層級已啟用的信任錨點。
- 如果路徑包含中繼憑證,用戶端必須在 TLS 交握期間提供這些憑證。
- 設定的信任錨點與用戶端憑證鏈必須通過標準 X.509 用戶端憑證路徑驗證。
如果一次上傳多張採用 PEM 編碼的憑證,驗證請求提供的憑證鏈時,只會使用設定中的第一張憑證作為錨點。請勿假設系統會將上傳內容當作 PEM 憑證組合處理。
OpenAI 不會從授權單位資訊存取(AIA)網址擷取缺少的中繼憑證,也不會透過憑證撤銷清單(CRL)或線上憑證狀態通訊協定(OCSP)進行檢查。請提供所需的完整憑證鏈,並運用憑證輪替、憑證停用及你自己的憑證生命週期管理措施來處理安全事件。
瞭解驗證順序
OpenAI 會先檢查專案層級已啟用的憑證,再檢查組織層級已啟用的憑證。如果這兩個層級都沒有已啟用的憑證,mTLS 就不會對請求額外執行憑證檢查。
如果有已啟用的憑證,OpenAI 會依下列順序驗證用戶端身分:
- OpenAI 會先嘗試既有的直接驗證路徑。這條路徑直接依據已啟用的錨點驗證用戶端憑證,不使用請求提供的中繼憑證。
- 如果直接驗證只是找不到相符的錨點,OpenAI 會改用 TLS 連線提供的用戶端憑證與中繼憑證,嘗試驗證請求提供的憑證鏈。
- 如果路徑通過驗證,而且已啟用的憑證設有 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是主體別名(SAN)清單,每個項目都有type、value和oid欄位。支援的 SAN 類型識別碼為DNS、EMAIL、IP_ADDRESS、URI和CUSTOM。
例如,下列篩選器要求憑證的組織單位為 Production,且至少有一個 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.openai.com |
預設 API mTLS 主機。 |
mtls-us.api.openai.com |
美國區域的 API mTLS 主機。 |
mtls-eu.api.openai.com |
歐盟區域的 API mTLS 主機。 |
mTLS 以主機為單位運作。請沿用呼叫對應 API 介面時使用的 /v1 路由,並測試工作負載使用的每個 API 和模型。各區域主機支援的路由和模型可能不同。
例如,將平常使用的 Bearer 認證資料與用戶端憑證一併傳送至預設 mTLS 主機:
export 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。交換憑證後會取得短效 Bearer 權杖,無法僅憑憑證完成 API 身分驗證。如需完整的請求格式,請參閱工作負載身分權杖交換參考文件。
輪替憑證
輪替時,請讓新舊信任錨點同時啟用一段時間,讓現有工作負載能持續運作:
- 上傳新的信任錨點,並保持舊錨點啟用。
- 在每個目標專案或組織層級啟用新錨點。
- 更新工作負載,使其提供可透過憑證鏈連至新錨點的用戶端憑證,再測試各工作負載使用的每個 mTLS 主機與 API 介面。
- 等所有工作負載都切換到新錨點後,再停用舊錨點。
- 必須先在組織和每個專案中停用舊憑證,才能將其刪除。
你可以輪替中繼憑證,無須變更已設定的信任錨點。請在後續請求中提供新的完整憑證鏈。
排解請求問題
請依據下列固定的錯誤代碼,區分設定錯誤與暫時性服務錯誤:
| 錯誤代碼 | 檢查事項 |
|---|---|
certificate_required |
有已啟用的憑證適用於此請求,但請求未提供必要的用戶端憑證資料。 |
invalid_certificate |
OpenAI 無法解碼或剖析用戶端憑證,或憑證缺少驗證所需的 AKI。 |
certificate_verification_failed |
用戶端憑證或提供的憑證鏈無法連至已啟用的信任錨點。 |
certificate_attribute_verification_failed |
憑證路徑已通過驗證,但 CEL 篩選器拒絕了已通過驗證的用戶端憑證。 |
authentication_temporarily_unavailable |
驗證器逾時、內部相依服務發生錯誤,或 CEL 運算式求值器發生錯誤,導致服務傳回 HTTP 503。請依照平常處理暫時性錯誤的策略重試。 |
對於管理請求,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 工作負載身分聯合不會傳回重新整理權杖,也不使用 DPoP、
cnf宣告或與憑證繫結的 Bearer 權杖。請參閱使用 X.509 憑證設定工作負載身分聯合。