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

為 Idira 設定工作負載身分聯邦

使用 Idira Secure Workload Access(SWA)即可呼叫 OpenAI API,無須儲存 OpenAI API 金鑰。SWA 會為工作負載指派 SPIFFE ID,並簽發 JWT-SVID。JWT-SVID 是代表該身分的已簽署權杖。OpenAI SDK 會用這個權杖換取短效的 OpenAI 存取權杖,其權限來自對應的服務帳戶。

本指南說明如何設定 OpenAI API。如果使用 Codex,請先依照本頁的步驟將權杖提供給工作負載,再依照在 Codex 中使用工作負載身分的說明操作。

開始前的準備

請確認您具備以下條件:

  • 已部署 SWA,並設定信任網域及證明政策,讓工作負載取得預期的 SPIFFE ID。
  • 工作負載可存取 SWA Agent 的 Workload API 通訊端。
  • 您有權在 OpenAI 組織中管理工作負載身分提供者、服務帳戶對應、專案及服務帳戶。
  • 您使用的 OpenAI SDK 支援工作負載身分憑證。

請依照 Idira 的 OpenAI 整合指南所列的先決條件,完成 SWA 基礎架構設定。

取得簽發者資訊與簽署金鑰

取得信任網域的 jwt.discovery_endpoints.oidc_discovery_url 和 jwt.discovery_endpoints.jwks_uri。請依照 Idira 的 OIDC 設定說明查詢這兩個值。

OpenAI 必須能在不提供憑證的情況下,透過 HTTPS 存取探索文件和 JWKS。權杖的 iss 宣告以 HTTPS URL 識別簽發者。sub 中的 SPIFFE ID 則用來識別工作負載。

為存取 OpenAI 選擇專用的對象值,例如 https://api.openai.com/v1。要求 JWT-SVID 和設定 OpenAI 身分提供者時,請使用相同的值。對象值用來識別權杖的預期接收方,無法用來設定權杖交換端點。

SWA 預設使用 RS512 和 4096 位元 RSA 金鑰進行簽署。OpenAI 的 JWT 驗證器支援這個組合。如需其他 SWA 簽署選項,請參閱 Idira 的 JWT 需求。

為工作負載提供最新的 JWT-SVID

在工作負載環境中安裝 spiffe-helper,以便向 SWA Agent 要求並更新 JWT-SVID。將以下設定儲存為 helper.conf。輔助程式會將權杖寫入 /var/run/spiffe/openai.jwt,這也是共用 SPIFFE SDK 範例使用的路徑:

agent_address = "/tmp/swa-agent/public/api.sock"
cert_dir      = "/var/run/spiffe"
daemon_mode   = true

jwt_svids = [{
  jwt_audience       = "https://api.openai.com/v1"
  jwt_svid_file_name = "openai.jwt"
}]

在 Kubernetes 中,請在工作負載的 Pod 內以 sidecar 容器執行輔助程式。將以記憶體為儲存媒介的 emptyDir 磁碟區掛載至 /var/run/spiffe,供工作負載與輔助程式共用,並將 SWA 通訊端的上層目錄 /tmp/swa-agent/public 掛載至輔助程式的容器。在虛擬機器上,請使用 /run/swa-agent/api.sock 作為 agent_address 的值,並將權杖目錄放在以記憶體為儲存媒介的空間中。請依照 Idira 的部署說明設定通訊端存取權與工作負載證明。

啟動輔助程式前,請先建立權杖目錄,並授予輔助程式寫入權限。在 sidecar 容器或虛擬機器服務中,使用這份設定啟動輔助程式:

spiffe-helper -config helper.conf

只允許需要權杖檔案或代理程式通訊端的程序存取相應資源。請讓輔助程式持續執行,以便在權杖到期前更換權杖。

如果您使用的程式語言有 SPIFFE Workload API 用戶端,也可以在主體權杖提供者中直接取得新的 JWT-SVID。請參閱 Idira 整合指南中直接使用 Workload API 的做法。

檢查權杖

在工作負載內讀取權杖,並將其存入本機解碼器使用的環境變數:

export TOKEN="$(cat /var/run/spiffe/openai.jwt)"
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]));

建立 OpenAI 身分提供者之前,請檢查下列欄位:

欄位 預期值
標頭 alg 設定的簽署演算法,例如 RS512。
標頭 kid 信任網域的公開 JWKS 中某個簽署金鑰的 ID。
iss 信任網域的 HTTPS 簽發者 URL。
sub 指派給這個工作負載的 SPIFFE ID。
aud 包含您為存取 OpenAI 選定的對象值。
iat 和 exp 權杖的簽發時間與到期時間。請使用尚未到期的權杖。

解碼器只會讀取宣告,不會驗證簽章。請勿將權杖寫入記錄檔或貼到網頁版解碼器中。檢查完畢後,請取消設定 TOKEN 環境變數。

設定 OpenAI 工作負載身分聯邦

建立工作負載身分提供者

前往組織設定 > 安全性 > 工作負載身分提供者,使用下列設定建立提供者:

設定 值
名稱 唯一的名稱,例如 idira-prod。
說明 填寫使用此提供者的應用程式與環境。
OIDC 簽發者 URL JWT-SVID 的 iss 值。
對象 輔助程式要求的對象值,例如 https://api.openai.com/v1。
使用上傳的 JWKS 驗證權杖 保持關閉,以使用 OIDC 探索。
屬性轉換 直接使用 sub 建立對應時,請留白。

OpenAI API 在交換權杖時,比對簽發者 URL 會忽略結尾的斜線。例如,https://issuer.example.com 和 https://issuer.example.com/ 會視為相符。其餘字元都必須完全相符,包括通訊協定和路徑。對象值也必須完全相符。請直接複製權杖中的簽發者值,讓設定保持一致。

如果 OpenAI 無法存取探索文件或 JWKS,請依照提供者的通用設定指南上傳公開 JWKS。SWA 輪替簽署金鑰時,請同步更新已上傳的金鑰。

將 SPIFFE ID 對應至服務帳戶

  1. 在提供者中建立服務帳戶對應並命名,例如 idira-production-workload。
  2. 將鍵設為 sub,並將值設為與工作負載權杖中完全相同的 SPIFFE ID,例如 spiffe://prod.example.com/k8s-nodegroup/ns/my-namespace/sa/my-service-account。
  3. 選取工作負載可使用的專案和服務帳戶。
  4. 選取工作負載所需的權限,例如用於模型請求的 api.model.request。這些權限可以縮小服務帳戶的存取範圍,但無法授予超出該範圍的存取權。權限欄位留白時,工作負載身分聯邦(WIF)不會額外限制存取權。

每個應用程式在每個環境中都應使用各自的服務帳戶。請優先使用完整的 SPIFFE ID 進行精確比對。只有在具有相同前綴的所有身分都應獲得相同存取權時,才在結尾使用萬用字元。請避免對應範圍重疊。詳情請參閱 SPIFFE 服務帳戶對應。

在程式碼中使用權杖

在工作負載的環境變數中設定 OpenAI 身分提供者的 ID 和所選服務帳戶的 ID:

export OPENAI_IDENTITY_PROVIDER_ID="<workload identity provider ID>"
export OPENAI_SERVICE_ACCOUNT_ID="<service account ID>"

以下共用 SPIFFE 範例會讀取 /var/run/spiffe/openai.jwt。每當 SDK 需要換取或更新 OpenAI 存取權杖時,主體權杖提供者就會傳回目前的權杖。SWA 和輔助程式負責更新外部 JWT-SVID,OpenAI SDK 則負責管理 OpenAI 存取權杖。

使用 Idira 簽發的 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);

驗證與疑難排解

在已通過證明的工作負載內執行範例,並確保未設定 OPENAI_API_KEY。請求成功時,範例會印出模型的回覆。請確認在輔助程式更換 JWT-SVID 且 SDK 更新 OpenAI 存取權杖後,請求仍能成功。

狀況 檢查項目
輔助程式未取得身分 確認工作負載符合 SWA 證明政策,且可存取代理程式通訊端。請在工作負載的執行環境中檢查。
權杖檔案不存在、內容空白,或檔案中的權杖已到期 確認輔助程式正在執行、共用磁碟區和檔案路徑與設定相符,且工作負載可讀取檔案。請保持各主機的時鐘同步。
權杖驗證失敗 檢查 iss、aud、kid 和權杖到期時間,並確認能否存取探索文件與 JWKS。請依照前述規則比對簽發者。
沒有相符的服務帳戶對應 檢查提供者 ID、服務帳戶 ID 和已啟用的對應,並確認 sub 的值完全相符。
有多個相符的對應 縮小重疊對應的範圍,或停用其中部分對應,讓已啟用的對應中只有一個相符。
權杖交換成功,但 API 拒絕請求 檢查對應服務帳戶所屬的專案、帳戶權限及適用的 API 存取政策。

如需診斷 SWA 部署問題,請參閱 Idira 的整合疑難排解說明。