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

使用 X.509 憑證設定工作負載身分聯盟

使用經驗證的用戶端憑證所代表的身分,換取短效 OpenAI 存取權杖。

透過 X.509 工作負載身分聯盟,工作負載可以使用 TLS 用戶端憑證所代表的身分換取短效 OpenAI 存取權杖。之後,工作負載會同時使用存取權杖和符合要求的用戶端憑證呼叫 OpenAI API。此流程以存取權杖取代 API 金鑰,仍須使用用戶端憑證。

OpenAI API 支援 X.509 工作負載身分聯盟。Codex 不支援此方式。使用 Codex 時,請使用 OIDC 權杖或 SPIFFE JWT-SVID。

如需權杖交換請求和回應的詳細資訊,請參閱工作負載身分權杖交換參考文件。如需瞭解雙向 TLS 的權限、憑證要求、啟用方式、mTLS 主機和憑證輪替,請參閱雙向 TLS 指南。

運作方式

使用 X.509 交換工作負載身分權杖的流程分為五個步驟:

  1. 貴組織在現有的雙向 TLS 設定中上傳並啟用受信任的根憑證。
  2. X.509 工作負載身分提供者會從已驗證的用戶端憑證推導出 openai.* 屬性。其中必須包含一個非空的 openai.subject 值。
  3. 服務帳戶對應會授權推導出的身分使用專案中的一個 OpenAI 服務帳戶。
  4. 工作負載向 mtls.auth.openai.com 上的 X.509 權杖端點出示憑證,並請求短效持有人權杖。憑證透過 TLS 連線提供,請求主體不含 subject_token。
  5. 工作負載向 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 提供者:

  1. 開啟組織設定 > 安全性 > 工作負載身分提供者,然後選取建立身分提供者。
  2. 選擇 X.509 作為提供者類型,然後輸入名稱,也可填寫說明。X.509 提供者不使用 OIDC 簽發者、對象、探索或 JWKS 設定。建立後即無法變更提供者類型。
  3. 如需在查找對應之前拒絕不符合條件的憑證,可在進階設定的屬性條件中新增 CEL 運算式。
  4. 在屬性轉換下,為必要的 openai.subject 轉換輸入非空的運算式。選取 X.509 時,控制台會新增 subject 這一列,並顯示及套用 openai. 前置詞。請選擇一項能穩定識別工作負載的憑證資訊。
  5. 如有需要,可使用其他不重複的 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"

建立服務帳戶對應

  1. 在 X.509 提供者的詳細資料頁面上,選取建立對應。
  2. 選取目標專案和服務帳戶,並只授予工作負載所需的 API 權限。
  3. 在鍵和值欄位中,指定必須完全相符的 openai.subject 值。X.509 對應允許不指定任何斷言,此時以空物件({})表示。如果指定斷言,每個鍵都必須以 openai. 開頭。
  4. 選取建立。

例如:

鍵 值
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 端點,並自動更新短效存取權杖。

使用 X.509 用戶端憑證驗證身分
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。