透過 X.509 工作負載身分聯盟,工作負載可以使用 TLS 用戶端憑證所代表的身分換取短效 OpenAI 存取權杖。之後,工作負載會同時使用存取權杖和符合要求的用戶端憑證呼叫 OpenAI API。此流程以存取權杖取代 API 金鑰,仍須使用用戶端憑證。
OpenAI API 支援 X.509 工作負載身分聯盟。Codex 不支援此方式。使用 Codex 時,請使用 OIDC 權杖或 SPIFFE JWT-SVID。
如需權杖交換請求和回應的詳細資訊,請參閱工作負載身分權杖交換參考文件。如需瞭解雙向 TLS 的權限、憑證要求、啟用方式、mTLS 主機和憑證輪替,請參閱雙向 TLS 指南。
運作方式
使用 X.509 交換工作負載身分權杖的流程分為五個步驟:
- 貴組織在現有的雙向 TLS 設定中上傳並啟用受信任的根憑證。
- X.509 工作負載身分提供者會從已驗證的用戶端憑證推導出
openai.*屬性。其中必須包含一個非空的openai.subject值。 - 服務帳戶對應會授權推導出的身分使用專案中的一個 OpenAI 服務帳戶。
- 工作負載向
mtls.auth.openai.com上的 X.509 權杖端點出示憑證,並請求短效持有人權杖。憑證透過 TLS 連線提供,請求主體不含subject_token。 - 工作負載向
mtls.api.openai.com上的 API 路由出示持有人權杖和用戶端憑證,以取得 API 授權。
API 處理請求時,會分別檢查持有人權杖和憑證是否符合授權要求。僅憑憑證無法取得呼叫 OpenAI API 的授權。
開始之前
請先備妥下列項目:
- 管理貴組織雙向 TLS 憑證和工作負載身分提供者的權限。
- 供工作負載使用的專案和服務帳戶。
- 用戶端憑證、對應的私密金鑰,以及建立通往受信任根憑證的憑證鏈所需的所有中繼憑證。
- 已在組織或專案層級啟用的受信任根憑證。
請將私密金鑰存放在版本控制系統之外,僅允許使用金鑰的工作負載存取該金鑰。請勿將私密金鑰、憑證內容或傳回的存取權杖寫入日誌。
設定雙向 TLS 憑證信任關係
X.509 工作負載身分提供者會沿用貴組織現有的雙向 TLS 憑證設定。提供者本身不會上傳憑證,也不會另外維護憑證信任存放區。
請先參閱雙向 TLS 指南,瞭解憑證要求、mTLS 主機、憑證啟用後的行為、CEL 篩選器和用戶端設定。接著開啟組織設定 > 安全性 > 雙向 TLS,上傳 PEM 格式的受信任憑證,並為整個組織或每個將使用 X.509 工作負載身分聯盟的專案啟用該憑證。
如果用戶端憑證透過中繼憑證連到根憑證,請設定穩定的信任錨點,並在 TLS 交握時先出示葉憑證,再依序出示目前使用的中繼憑證。OpenAI 會使用請求提供的中繼憑證,不會從憑證中的 URL 取得缺少的中繼憑證。
設定 X.509 提供者
請依下列步驟設定 X.509 提供者:
- 開啟組織設定 > 安全性 > 工作負載身分提供者,然後選取建立身分提供者。
- 選擇 X.509 作為提供者類型,然後輸入名稱,也可填寫說明。X.509 提供者不使用 OIDC 簽發者、對象、探索或 JWKS 設定。建立後即無法變更提供者類型。
- 如需在查找對應之前拒絕不符合條件的憑證,可在進階設定的屬性條件中新增 CEL 運算式。
- 在屬性轉換下,為必要的
openai.subject轉換輸入非空的運算式。選取 X.509 時,控制台會新增subject這一列,並顯示及套用openai.前置詞。請選擇一項能穩定識別工作負載的憑證資訊。 - 如有需要,可使用其他不重複的
openai.*名稱新增轉換,然後選取建立。
例如,下列設定使用憑證的一般名稱作為標準主體識別值,並將組織單位設為額外的對應屬性:
[
{
"attribute": "openai.subject",
"expression": "assertion.subject.common_name"
},
{
"attribute": "openai.environment",
"expression": "assertion.subject.organizational_unit"
}
]
可從 assertion.subject 和 assertion.subject_alt_names 取得憑證資訊。用於對應的轉換結果必須是純量值。每個額外轉換的 openai.* 名稱都必須是唯一的。
例如,可使用下列屬性條件運算式,讓提供者只接受正式環境的憑證:
assertion.subject.organizational_unit == "Production"
建立服務帳戶對應
- 在 X.509 提供者的詳細資料頁面上,選取建立對應。
- 選取目標專案和服務帳戶,並只授予工作負載所需的 API 權限。
- 在鍵和值欄位中,指定必須完全相符的
openai.subject值。X.509 對應允許不指定任何斷言,此時以空物件({})表示。如果指定斷言,每個鍵都必須以openai.開頭。 - 選取建立。
例如:
| 鍵 | 值 |
|---|---|
openai.subject |
payments-service-prod |
X.509 對應會比對推導出的 openai.* 屬性,不會比對 sub、iss 或 aud 等原始 JWT 宣告。
提供者清單會顯示提供者 ID,對應的詳細資料則會顯示選取的服務帳戶及其 ID。請記下這兩個 ID,工作負載會在交換權杖時傳送這兩個值。
透過 SDK 使用 X.509 工作負載身分
為憑證鏈、私密金鑰、提供者和服務帳戶設定環境變數:
export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"
export OPENAI_IDENTITY_PROVIDER_ID="idp_example"
export OPENAI_SERVICE_ACCOUNT_ID="svc_acct_example"
憑證鏈檔案應以葉憑證開頭,後面依序放入所需的中繼憑證。請勿在請求主體中加入憑證資料或 subject_token。
使用這些值設定 OpenAI SDK 用戶端。SDK 會在交換權杖和傳送 API 請求時出示用戶端憑證,將 API 請求送至 mTLS 端點,並自動更新短效存取權杖。
import { readFile } from "node:fs/promises";
import OpenAI from "openai";
import { workloadIdentity } from "openai/auth/x509-transport";
const certificatePath = process.env.OPENAI_MTLS_CERT_CHAIN;
const privateKeyPath = process.env.OPENAI_MTLS_KEY;
const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;
if (
!certificatePath ||
!privateKeyPath ||
!identityProviderId ||
!serviceAccountId
) {
throw new Error(
"Set OPENAI_MTLS_CERT_CHAIN, OPENAI_MTLS_KEY, OPENAI_IDENTITY_PROVIDER_ID, and OPENAI_SERVICE_ACCOUNT_ID"
);
}
const credential = workloadIdentity.fromX509({
certificateChain: await readFile(certificatePath, "utf8"),
privateKey: await readFile(privateKeyPath, "utf8"),
identityProviderId,
serviceAccountId,
});
try {
const client = new OpenAI({ credential });
const response = await client.responses.create({
model: "gpt-5.6-terra",
input: "Say hello from X.509 workload identity federation.",
});
console.log(response.output_text);
} finally {
await credential.close();
}這些範例需要使用支援上述 X.509 設定的 OpenAI SDK 版本:TypeScript 7.8.0 以上(須安裝 undici 同儕相依套件)、Python 3.6.0 以上、Go 3.54.0 以上、Java 4.55.0 以上或 Ruby 0.83.0 以上。
Java 範例會載入 PKCS12 金鑰存放區來建立 X509ExtendedKeyManager,並使用平台預設的信任存放區來建立 X509TrustManager。執行此範例時,請設定 OPENAI_X509_KEYSTORE_PATH、OPENAI_X509_KEYSTORE_PASSWORD 和 OPENAI_X509_CERTIFICATE_ALIAS。也可以向 SDK 提供以 PEM 或硬體為基礎的管理器。
手動使用憑證交換權杖
若要直接檢視或實作權杖交換協定,請向 X.509 權杖端點出示憑證:
curl --cert "$OPENAI_MTLS_CERT_CHAIN" \
--key "$OPENAI_MTLS_KEY" \
--request POST "https://mtls.auth.openai.com/oauth/token" \
--header "Content-Type: application/json" \
--data @- <<JSON
{
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"subject_token_type": "urn:openai:params:oauth:token-type:x509",
"identity_provider_id": "${OPENAI_IDENTITY_PROVIDER_ID}",
"service_account_id": "${OPENAI_SERVICE_ACCOUNT_ID}"
}
JSON
交換成功後,端點會傳回一般的短效持有人權杖:
{
"access_token": "eyJ...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600,
"expires_at": 1789045200,
"scope": "api.model.read api.model.request"
}
只有在相符的服務帳戶對應已設定權限時,回應才會包含 scope 屬性。
範例中的到期時間僅供說明。如果已驗證的用戶端憑證較早到期,傳回的權杖有效期限可能會縮短。請參閱權杖交換回應欄位,瞭解 expires_in 和 expires_at 的單位和意義。
從成功回應中讀取 access_token 的值,並將其存入應用程式的認證資料存放區,或存入 OPENAI_WIF_ACCESS_TOKEN 等環境變數。請將此值視為機密資料,切勿將其輸出、寫入日誌或提交至版本控制系統。
手動呼叫 OpenAI API
將 OPENAI_MODEL 設為目前的預設模型 gpt-6-astra,或目標專案可使用的其他模型。然後向 API 的 mTLS 端點傳送持有人權杖和符合要求的用戶端憑證:
curl --request POST \
--cert "$OPENAI_MTLS_CERT_CHAIN" \
--key "$OPENAI_MTLS_KEY" \
--header "Authorization: Bearer $OPENAI_WIF_ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data "{\"model\":\"$OPENAI_MODEL\",\"input\":\"Say hello in one sentence.\"}" \
"https://mtls.api.openai.com/v1/responses"
請使用持有人權杖取代 API 金鑰,並繼續在 API 請求中出示符合要求的用戶端憑證。
持有人權杖與憑證之間沒有密碼學上的綁定關係。最直接的設定方式是在 API 請求中沿用交換權杖時出示的憑證。也可以使用另一張憑證,只要該憑證本身符合同一套現行 API mTLS 政策即可。
權杖有效期限與更新
X.509 工作負載身分權杖的有效期限最長為一小時,且不會晚於已驗證的用戶端憑證到期。交換時不會傳回重新整理權杖。若要取得新的存取權杖,請再次使用憑證交換權杖。
手動交換時,請將 expires_at 與存取權杖一併儲存,並排定在該時間戳記之前再次交換。請預留時間,以因應時鐘偏差和請求延遲。範例請參閱權杖更新指南。
輪替中繼憑證時,無須變更已設定的根憑證。請在後續的權杖交換和 API 請求中出示新的完整憑證鏈。
排解權杖交換問題
X.509 權杖交換會傳回通用的 OAuth 錯誤,不會透露憑證、根憑證、提供者或對應的詳細資訊。
| 結果 | 常見原因 |
|---|---|
HTTP 403 |
請求的方法或路徑不符。必須使用 POST /oauth/token,並將請求送至 mtls.auth.openai.com。 |
invalid_subject_token |
缺少 TLS 用戶端憑證或憑證無效、出示的憑證鏈無法連到已啟用的根憑證、憑證不在有效期間內,或雙向 TLS 憑證准入規則拒絕該憑證。 |
invalid_grant |
提供者或對應無效或已停用、提供者的屬性條件運算式拒絕該身分、沒有已啟用且適用的根憑證,或找不到相符的對應。 |
| 伺服器錯誤 | OpenAI 傳回暫時性伺服器錯誤。請依照平常處理暫時性錯誤的策略重試。 |
X.509 權杖交換失敗時,絕不會改用 OIDC 或一般 OAuth 流程。
限制
- X.509 工作負載身分提供者不會另外維護憑證信任存放區。
- 持有人權杖未綁定憑證,也不使用 DPoP 或
cnf宣告。 - 使用憑證交換權杖並不代表只靠憑證即可取得 API 授權。API 請求仍須同時提供持有人權杖和符合要求的用戶端憑證。
- OpenAI 不會從 AIA URL 取得缺少的中繼憑證。請在 TLS 協商期間出示完整的憑證鏈。
- OpenAI 在此流程中不會檢查憑證撤銷清單(CRL),也不會執行 OCSP 檢查。規劃憑證安全事件的應變措施時,請考量雙向 TLS 根憑證、提供者和對應的管理機制,以及已簽發權杖的短效特性。
- 此流程未新增對 SPIFFE X.509-SVID 的支援。SPIFFE 指南仍使用 JWT-SVID。