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

為 SPIFFE 設定工作負載身分聯盟

使用 SPIFFE 作為工作負載身分提供者,即可用 SPIFFE JWT-SVID 換取短效的 OpenAI 存取權杖。這樣一來,通過 SPIRE 或其他 SPIFFE 相容身分提供者驗證的工作負載,就能呼叫 OpenAI API,無須儲存長效 API 金鑰。

如果使用 Idira Secure Workload Access,請依照 Idira 設定指南設定代理程式與權杖傳遞方式。

OpenAI 支援以 SPIFFE JWT-SVID 作為 JWT 主體權杖,前提是權杖包含簽發者、目標對象、到期時間和簽發時間戳記,且 OpenAI 可透過 JWKS 驗證其簽章。OpenAI 不支援以 SPIFFE X.509-SVID 作為工作負載身分聯盟的主體權杖。

JWT-SVID 規格要求權杖包含 sub、aud 和 exp 宣告。若要搭配 OpenAI 使用 JWT-SVID,權杖還必須包含 iss 和 iat 宣告,以及 kid 標頭欄位,讓 OpenAI 能依據工作負載身分提供者的設定驗證權杖。

JWT-SVID 並非 OpenID Connect ID 權杖。SPIRE OIDC Discovery Provider 提供探索中繼資料和 JWKS 金鑰,讓 OpenAI 能驗證 JWT-SVID。這不會改變權杖在 SPIFFE 中的語意,也不需要執行 OIDC 登入流程。

如需瞭解 SPIFFE 術語和權杖要求,請參閱 SPIFFE 的 JWT-SVID 規格和 Workload API 規格。

設定 SPIFFE

設定 SPIFFE 提供者,讓它為需要呼叫 OpenAI API 的工作負載簽發 JWT-SVID。以下說明採用 SPIRE 術語。只要 SPIFFE 相容提供者簽發的 JWT-SVID 包含 OpenAI 可驗證的簽發者資訊,並提供可供 OpenAI 驗證簽章的 JWKS 金鑰,就能使用相同的 OpenAI 設定。

SPIFFE 環境必須提供下列項目:

  • 工作負載的固定 SPIFFE ID,例如 spiffe://example.org/ns/production/sa/openai-wif。
  • 專供存取 OpenAI 使用的單一 JWT-SVID 目標對象,例如 https://api.openai.com/v1,或自行選擇的其他不透明識別值。
  • JWT 簽發者網址,須列於 JWT-SVID 的 iss 宣告中,供 OpenAI 驗證。
  • 用於驗證 JWT-SVID 簽章的公開 JWKS,可透過 OIDC 探索或上傳 JWKS 提供。
  • 讓工作負載能從 SPIFFE Workload API 取得最新 JWT-SVID 的方式。

目標對象是必須完全相符的識別碼,不一定是接收 JWT-SVID 的端點。可以使用 https://api.openai.com/v1 或其他服務專用值,只要 SPIFFE Workload API 請求中的值與 OpenAI 提供者設定中的值相同即可。

可行時,請透過 SPIRE OIDC Discovery Provider 提供 SPIFFE 簽發者的探索資訊。將 SPIRE Server 的 jwt_issuer 和 OIDC Discovery Provider 的 jwt_issuer 都設為同一個 HTTPS 簽發者網址,並在 OpenAI 中設定相同的網址。

在 SPIRE Server 設定中:

server {
  trust_domain = "example.org"
  jwt_issuer   = "https://spire-oidc.example.org"
}

在獨立的 SPIRE OIDC Discovery Provider 設定中:

# Relevant issuer fields only
domains    = ["spire-oidc.example.org"]
jwt_issuer = "https://spire-oidc.example.org"

設定 OIDC Discovery Provider 時,還需要指定金鑰資料來源,例如 server_api、workload_api 或 file,以及提供服務的方式,例如使用 ACME、TLS 憑證或 Unix 通訊端。如需完整的設定選項,請參閱 SPIRE OIDC Discovery Provider 文件。

SPIFFE 信任網域與 JWT 簽發者是兩個不同的概念。在本例中,JWT-SVID 的主體是 example.org 信任網域中的 SPIFFE ID,而簽發者則以 HTTPS 簽發者網址表示:

{
  "sub": "spiffe://example.org/ns/production/sa/openai-wif",
  "iss": "https://spire-oidc.example.org"
}

SPIRE OIDC Discovery Provider 提供 OIDC 探索文件和 JWKS 端點。停用 使用已上傳的 JWKS 驗證權杖 時,OpenAI 即可使用這兩者。

如果 OpenAI 無法連線至簽發者的探索端點,請改用上傳 JWKS 的模式。在此模式下,OpenAI 仍會比對工作負載身分提供者設定中的簽發者與 JWT-SVID 的 iss 宣告,但會使用儲存在該提供者設定中的 JWKS JSON 驗證簽章。

注意: 依 SPIFFE JWT-SVID 規格,JWT 標頭中的 kid 為選用欄位,但 OpenAI 要求 JWT 主體權杖的標頭必須包含 kid,以便從設定的 JWKS 中選取簽署金鑰。如果 SPIFFE 提供者可能省略 kid,請將其設定為在用於 OpenAI 工作負載身分聯盟的權杖中包含此欄位。

若要在能呼叫 SPIFFE Workload API 的工作負載中檢查 JWT-SVID,請使用預計在 OpenAI 中設定的目標對象來請求權杖。請在與應用程式相同的工作負載執行環境中執行下列指令,因為 Workload API 會依呼叫端處理程序的身分決定是否授權。

TOKEN=$(spire-agent api fetch jwt \
  -socketPath /run/spire/sockets/agent.sock \
  -audience "https://api.openai.com/v1" | sed -n '2p')
export TOKEN

如果工作負載有多個 SPIFFE ID,請在請求中指定要使用的身分:

TOKEN=$(spire-agent api fetch jwt \
  -socketPath /run/spire/sockets/agent.sock \
  -spiffeID "spiffe://example.org/ns/production/sa/openai-wif" \
  -audience "https://api.openai.com/v1" | sed -n '2p')
export TOKEN

驗證權杖

設定工作負載身分聯盟之前,請先將 JWT-SVID 匯出為環境變數 TOKEN,再於本機執行下列其中一個範例,檢查權杖的標頭和宣告:

const parts = process.env.TOKEN?.split(".") ?? [];
if (parts.length !== 3) {
  throw new Error("Expected a compact JWT with three segments");
}

const decode = (segment: string) => {
  if (!/^[A-Za-z0-9_-]+$/.test(segment) || segment.length % 4 === 1) {
    throw new Error("JWT segment is not valid Base64URL");
  }
  const bytes = Buffer.from(segment, "base64url");
  if (bytes.toString("base64url") !== segment) {
    throw new Error("JWT segment is not valid Base64URL");
  }
  const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
  const value = JSON.parse(decoded);
  if (value === null || Array.isArray(value) || typeof value !== "object") {
    throw new Error("JWT segment is not a JSON object");
  }
  return decoded;
};

console.log("Header:");
console.log(decode(parts[0]));
console.log("\nPayload:");
console.log(decode(parts[1]));

這些範例只會解碼 JWT,不會驗證權杖簽章。對於正式環境的權杖,請使用本機解碼工具,避免將權杖貼到第三方工具中。

解碼後的 SPIFFE JWT-SVID 類似以下範例:

{
  "alg": "ES256",
  "kid": "jwt-svid-key-1"
}
{
  "iss": "https://spire-oidc.example.org",
  "aud": ["https://api.openai.com/v1"],
  "sub": "spiffe://example.org/ns/production/sa/openai-wif",
  "iat": 1716235422,
  "exp": 1716235722
}

交換權杖之前,請將收到的權杖解碼,並與 OpenAI 設定比對。檢查標頭中的 alg 和 kid,以及酬載中的 iss、aud、sub、iat 和 exp。alg 的實際值取決於 SPIRE Server 的 JWT 簽署金鑰設定。

設定工作負載身分聯盟

在 OpenAI 中為 SPIFFE JWT-SVID 簽發者建立工作負載身分提供者,再新增與受信任 SPIFFE ID 相符的服務帳戶對應規則。

設定工作負載身分提供者

  1. 建立工作負載身分提供者。 將 名稱 設為不重複的值,例如 spiffe-prod。在 說明 中填入 Production SPIFFE workloads 等描述,方便管理員識別提供者。

  2. 設定簽發者與目標對象。 將 OIDC 簽發者網址 設為與 JWT-SVID 的 iss 宣告完全相同的值,例如 https://spire-oidc.example.org。將 目標對象 設為向 SPIFFE Workload API 請求權杖時指定的目標對象值。本例使用 https://api.openai.com/v1。

  3. 選擇 JWKS 來源。 如果 OpenAI 能連線至 SPIRE OIDC Discovery Provider,請保持停用 使用已上傳的 JWKS 驗證權杖。OpenAI 會透過 OIDC 探索取得 JWKS,並用它驗證 JWT-SVID 簽章。

    如果 OpenAI 無法連線至簽發者,請啟用 使用已上傳的 JWKS 驗證權杖,然後將 JWKS JSON 設為 JWT-SVID 簽署金鑰的公鑰集合。請上傳完整的公開 JWKS 物件,包含列出各金鑰的 keys 陣列。請勿包含私鑰資料。

  4. 只有在對應規則需要衍生屬性時,才新增屬性轉換。 直接使用 sub 建立對應規則時,無須轉換屬性。只有在需要從一或多個權杖宣告推導出對應值時,才使用屬性轉換。如需瞭解轉換方式,請參閱工作負載身分聯盟主指南。

設定服務帳戶對應規則

  1. 建立服務帳戶對應規則。 將 名稱 設為在該工作負載身分提供者中不重複的值,例如 production-openai-wif。在 說明 中填入 Production SPIFFE workload for OpenAI API access 等描述,說明哪些工作負載可以使用此規則。

  2. 比對 SPIFFE ID。 將 索引鍵 設為 sub,並將 值 設為工作負載的 SPIFFE ID,例如 spiffe://example.org/ns/production/sa/openai-wif。

    對於具有特殊權限的工作負載,請優先採用完全相符的 SPIFFE ID。只有在具有同一前綴的每個 SPIFFE ID 都應能取得 OpenAI 存取權杖時,才在結尾使用萬用字元。例如,spiffe://example.org/ns/production/sa/* 允許所有符合此模式的正式環境服務帳戶路徑。

  3. 選擇 OpenAI 目標帳戶。 將 專案 設為目標服務帳戶所屬的 OpenAI 專案。將 服務帳戶 設為 SPIFFE 工作負載可使用的 OpenAI 服務帳戶,例如 spiffe-prod-openai-wif。如果希望為此對應規則建立新的服務帳戶,而非沿用現有帳戶,請勾選 Create a new service account in this project。

  4. 視需要縮小 API 權限範圍。 選取適當的 權限,例如 api.model.request 和 api.vector_store.read,進一步限制透過此對應規則簽發的存取權杖可執行的操作。如果不需要額外限制 WIF 的授權範圍,請將權限留白。權杖仍會以對應服務帳戶的身分取得授權。

在程式碼中使用權杖

設定 OpenAI SDK 用戶端,使用最新的 SPIFFE JWT-SVID 換取 OpenAI 簽發的存取權杖。

以下 SDK 範例假設 SPIFFE 整合程式會更新 JWT-SVID,並將其寫入 /var/run/spiffe/openai.jwt。請設定檔案權限,讓只有該工作負載能讀取檔案。JWT-SVID 的有效期很短,請在權杖到期前更新檔案。可行時,也可以在主體權杖提供者中使用對應程式語言的 SPIFFE 程式庫,直接從 SPIFFE Workload API 取得 JWT-SVID,避免讀取過期的權杖檔案。

在工作負載環境中設定 OPENAI_IDENTITY_PROVIDER_ID 和 OPENAI_SERVICE_ACCOUNT_ID。權杖檔案存放的是外部主體權杖。OPENAI_IDENTITY_PROVIDER_ID 用來識別 OpenAI 工作負載身分提供者,OPENAI_SERVICE_ACCOUNT_ID 則用來識別目標 OpenAI 服務帳戶。OpenAI 接著會根據權杖宣告,找出該提供者與服務帳戶下相符的對應規則。

使用 SPIFFE JWT-SVID 驗證身分
import { readFile } from "node:fs/promises";
import OpenAI from "openai";

const tokenPath = "/var/run/spiffe/openai.jwt";
const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;

if (!identityProviderId || !serviceAccountId) {
  throw new Error(
    "Set OPENAI_IDENTITY_PROVIDER_ID and OPENAI_SERVICE_ACCOUNT_ID"
  );
}

function spiffeJwtSvidProvider(path: string) {
  return {
    tokenType: "jwt" as const,
    getToken: async () => {
      const token = (await readFile(path, "utf8")).trim();
      if (!token) {
        throw new Error("The SPIFFE JWT-SVID file is empty.");
      }
      return token;
    },
  };
}

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId,
    serviceAccountId,
    provider: spiffeJwtSvidProvider(tokenPath),
  },
});

const response = await client.responses.create({
  model: "gpt-5.6-terra",
  input: "Say hello from SPIFFE workload identity federation.",
});

console.log(response.output_text);

SPIFFE 最佳做法

  • 請使用 JWT-SVID 進行 OpenAI 工作負載身分聯盟驗證。X.509-SVID 適用於雙向 TLS 驗證,但 OpenAI 權杖交換端點不接受 X.509-SVID。
  • 請使用單一且專供存取 OpenAI 使用的目標對象。避免使用整個信任網域或環境名稱等範圍過大的目標對象。
  • 盡可能要求 SPIFFE ID 完全相符。只有在刻意共用同一信任邊界時,才使用含萬用字元的對應規則。
  • 請縮短 JWT-SVID 的有效期,以降低持有者權杖遭重播的風險。OpenAI 存取權杖的到期時間不會晚於交換時使用的外部主體權杖。
  • 請謹慎輪替簽署金鑰。在輪替期間,透過 OIDC 探索同時發布新舊公鑰。如果使用上傳的公開 JWKS,請先更新 JWKS,再簽發帶有新 kid 的 JWT-SVID。
  • 請保持 SPIRE Server 與工作負載的時鐘同步。時鐘偏差過大時,原本有效的 JWT-SVID 可能會被判定為尚未生效、簽發時間過早或已過期,因而遭到拒絕。
  • 請保護 SPIFFE Workload API 通訊端。任何能取得工作負載 JWT-SVID 的處理程序,都可以嘗試用它換取 OpenAI 存取權。
  • 請讓 OpenAI 服務帳戶的權限範圍與應用程式及環境的權限邊界一致。請勿讓彼此無關的 SPIFFE 工作負載共用高權限服務帳戶。
  • 請監控權杖交換失敗的情形,檢查簽發者、目標對象、簽署金鑰或對應規則是否不符。