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

為 Google Cloud 設定工作負載身分聯盟

在下列兩種情境中,都可以使用 Google Cloud 作為工作負載身分提供者:

  • Google 工作負載身分: Google 會簽署 OIDC 權杖,並將權杖核發給工作負載所連結的 Google 服務帳戶。使用這個權杖換取短效 OpenAI 存取權杖。
  • Google Kubernetes Engine: 使用投射至工作負載的 GKE 服務帳戶權杖,換取短效 OpenAI 存取權杖。

Google 工作負載身分

Google Cloud 工作負載可以向 Google 中繼資料伺服器要求已簽署的 OIDC 身分權杖,無須儲存長效服務帳戶金鑰。在 OpenAI 工作負載身分聯盟中,Google 身分權杖就是主體權杖。OpenAI 會先驗證這個權杖,再核發 OpenAI 存取權杖。此流程適用於 Compute Engine、Cloud Run、使用已連結 Google 服務帳戶的 GKE 工作負載,以及其他提供中繼資料伺服器身分端點的 Google 代管執行環境。

設定 Google 工作負載身分

為需要呼叫 OpenAI API 的工作負載建立 Google 服務帳戶。如需完整設定流程,請參閱 Google 的建立服務帳戶指南。

例如,使用 Google Cloud CLI 建立服務帳戶:

gcloud iam service-accounts create openai-wif \
  --description="Service account for OpenAI workload identity federation" \
  --display-name="OpenAI workload identity federation"

建立 Compute Engine VM 時連結該服務帳戶,或將服務帳戶連結至執行應用程式的 Google Cloud 資源。該資源必須能在執行時呼叫 Google 中繼資料伺服器。如需 VM 設定步驟,請參閱 Google 的建立使用自管服務帳戶的 VM 指南。

請勿為此流程建立或下載服務帳戶金鑰。工作負載會使用已連結的服務帳戶向中繼資料伺服器要求短效 OIDC 權杖。

取得 Google 身分權杖

在已連結服務帳戶的 Google Cloud 資源上,向中繼資料伺服器要求 OIDC 身分權杖,並指定已設定的目標對象。OpenAI 會以這個主體權杖換發 OpenAI 存取權杖。

AUDIENCE="https://api.openai.com/v1"

TOKEN=$(curl -sS -G -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity" \
  --data-urlencode "audience=${AUDIENCE}")
export TOKEN

中繼資料伺服器會傳回 Google 簽署的 JWT。如需中繼資料伺服器身分端點的詳細資訊,請參閱 Google 的驗證 VM 身分指南。

驗證權杖

設定工作負載身分聯盟前,請先將 Google 身分權杖匯出為環境變數 TOKEN,再於本機執行下列指令碼,檢查權杖中的宣告:

const parts = process.env.TOKEN?.split(".") ?? [];
if (parts.length !== 3) {
  throw new Error("Expected a compact JWT with three segments");
}
if (!/^[A-Za-z0-9_-]+$/.test(parts[1]) || parts[1].length % 4 === 1) {
  throw new Error("JWT payload is not valid Base64URL");
}

const bytes = Buffer.from(parts[1], "base64url");
if (bytes.toString("base64url") !== parts[1]) {
  throw new Error("JWT payload is not valid Base64URL");
}
const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
const claims = JSON.parse(decoded);
if (claims === null || Array.isArray(claims) || typeof claims !== "object") {
  throw new Error("JWT payload is not a JSON object");
}
console.log(decoded);

這個指令會解碼 JWT 的酬載,但不會驗證權杖簽章。對於正式環境的權杖,請使用本機解碼器,避免將權杖貼到第三方工具中。

將 Google 中繼資料伺服器傳回的身分權杖解碼後,內容會類似下列範例:

{
  "iss": "https://accounts.google.com",
  "aud": "https://api.openai.com/v1",
  "azp": "110123456789012345678",
  "sub": "110123456789012345678",
  "email": "openai-wif@my-project.iam.gserviceaccount.com",
  "email_verified": true,
  "iat": 1716235422,
  "exp": 1716239022
}

使用解碼後的酬載,確認收到的權杖是否符合 OpenAI 中設定的核發者、目標對象及對應值。交換權杖前,檢查 iss、aud、email 和 sub 宣告,即可發現大多數設定問題。

設定工作負載身分聯盟

在 OpenAI 中為 Google 核發的身分權杖建立工作負載身分提供者,再新增服務帳戶對應規則,以權杖中穩定不變的宣告作為比對條件。

請先設定工作負載身分提供者,再建立服務帳戶對應規則。

設定工作負載身分提供者

  1. 建立工作負載身分提供者。 在名稱欄位輸入不重複的值,例如 google-workload-identity-prod。在說明欄位輸入有助於管理員辨識提供者的文字,例如 Production Google Cloud workloads。

  2. 設定核發者和目標對象。 將 OIDC 核發者網址設為 https://accounts.google.com。將目標對象設為工作負載向 Google 中繼資料伺服器要求權杖時指定的自訂目標對象,例如 https://api.openai.com/v1。這個值必須與權杖的 aud 宣告相符。

  3. 使用 Google 的 OIDC 探索機制。 請勿啟用使用上傳的 JWKS 驗證權杖。OpenAI 會使用 Google 的 OIDC 探索中繼資料和 JWKS,驗證 Google 簽署的身分權杖。

  4. 如果對應規則需要衍生屬性,請新增屬性轉換。 例如,輸入 subject 並指定運算式 assertion.sub,即可根據主體宣告建立 openai.subject。儀表板會自動加上 openai. 前置字串。若權杖的原始宣告以 openai. 開頭,除非設定了相應的轉換,否則系統在比對 openai. 對應鍵時會忽略這些宣告。

設定服務帳戶對應規則

  1. 建立服務帳戶對應規則。 在名稱欄位輸入在此工作負載身分提供者內不重複的值,例如 compute-openai-wif。在說明欄位指出哪些工作負載可以使用這項對應規則,例如 Production Compute Engine OpenAI API workload。

  2. 比對穩定不變的 Google 服務帳戶宣告。 針對每個必須相符的宣告,各新增一列並填入鍵和值。請使用 sub 作為繫結身分的主要依據,因為它穩定且唯一。為方便辨識,也可以一併比對 email。

  3. 選擇 OpenAI 端的目標。 將專案設為目標服務帳戶所屬的 OpenAI 專案。將服務帳戶設為 Google Cloud 工作負載可使用的 OpenAI 服務帳戶,例如 google-workload-identity-prod-openai-wif。

  4. 視需要限縮 API 權限。 選取適當的權限,例如 api.model.request 和 api.vector_store.read,進一步限制依此對應規則核發的存取權杖所能執行的操作。若不需要額外限制工作負載身分聯盟(WIF)的授權範圍,請將權限欄位留白。使用該權杖的要求仍會以對應服務帳戶的身分取得授權。

在程式碼中使用權杖

設定 OpenAI SDK 用戶端,讓它向中繼資料伺服器要求 Google 身分權杖,再用該權杖換取 OpenAI 核發的存取權杖。

將 OPENAI_WIF_AUDIENCE 設為工作負載身分提供者中設定的自訂目標對象。SDK 會要求適用於該目標對象的 Google 身分權杖,用它換取 OpenAI 核發的存取權杖,再使用 OpenAI 權杖為 API 要求進行身分驗證。

使用 Google 中繼資料伺服器的身分權杖進行驗證
import OpenAI from "openai";

const metadataEndpoint =
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity";

const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;
const audience = process.env.OPENAI_WIF_AUDIENCE;

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

function googleMetadataIdentityTokenProvider(audience: string) {
  return {
    tokenType: "jwt" as const,
    getToken: async () => {
      const url = new URL(metadataEndpoint);
      url.searchParams.set("audience", audience);
      url.searchParams.set("format", "full");

      const response = await fetch(url, {
        headers: { "Metadata-Flavor": "Google" },
      });

      if (!response.ok) {
        throw new Error(
          `Google metadata token request failed with status ${response.status}.`
        );
      }

      const token = (await response.text()).trim();
      if (!token) {
        throw new Error(
          "Google metadata server did not return an identity token."
        );
      }

      return token;
    },
  };
}

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

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

console.log(response.output_text);

Google Cloud 最佳做法

  • 為每個工作負載使用專屬的 Google 服務帳戶。避免讓無關的服務或環境共用服務帳戶。
  • 使用工作負載身分驗證流程取代長效服務帳戶金鑰。對於可使用中繼資料伺服器身分權杖或 GKE Workload Identity 的工作負載,請避免分發和輪替 JSON 金鑰檔案。
  • 在實務可行的前提下,將每個身分的使用範圍限制在盡可能小的工作負載範圍內。為各應用程式分設服務帳戶,有助於在稽核時辨識存取來源,並落實最小權限原則。
  • 謹慎使用以屬性為依據的對應規則。盡可能優先使用穩定的識別資訊,例如服務帳戶的主體宣告,避免依賴可能變動的中繼資料。
  • 將正式環境與非正式環境分設於不同專案。分開管理專案可降低意外共用權限的風險,並簡化稽核作業。
  • 僅授予必要的 IAM 權限。將 Google 身分的權限限制在工作負載所需的範圍內。
  • 監控服務帳戶的使用情形。非預期的權杖交換可能表示設定已偏離預期,或工作負載已遭入侵。