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

為 GitHub Actions 設定工作負載身分識別同盟

將 GitHub Actions 設為工作負載身分提供者後,工作流程即可使用 GitHub 核發的 OIDC 權杖換取短效 OpenAI 存取權杖。這樣一來,工作流程就能向 OpenAI API 驗證身分,無須將長效 API 金鑰儲存在 GitHub 的機密資料中。

如果工作流程中的作業具備 id-token: write 權限並要求身分權杖,GitHub 就能為該作業簽發 OIDC JWT。OpenAI 會先驗證權杖的簽發者、對象、簽章和對應屬性,再核發 OpenAI 存取權杖。

設定 GitHub Actions

授予工作流程或作業要求 GitHub OIDC 權杖的權限:

permissions:
  id-token: write
  contents: read

id-token: write 權限允許作業要求 OIDC JWT,但不會授予寫入程式碼庫內容的權限。contents: read 則是 actions/checkout 所需的權限。

要求權杖時,指定的對象值必須與 OpenAI 工作負載身分提供者中設定的值完全相同。自訂 JavaScript 動作可以呼叫 core.getIDToken("your-wif-audience"),Shell 步驟則可以直接呼叫 GitHub 的 OIDC 要求網址。如果對象值含有 URL 保留字元,例如 https://api.openai.com/v1,請先對該值進行 URL 編碼,再附加至要求網址:

AUDIENCE="https://api.openai.com/v1"
ENCODED_AUDIENCE=$(jq -rn --arg audience "$AUDIENCE" '$audience | @uri')

TOKEN=$(curl -sSf -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=${ENCODED_AUDIENCE}" | jq -r .value)
export TOKEN

GitHub OIDC 權杖的重要宣告包括:

  • iss:權杖簽發者。GitHub Actions 的簽發者為 https://token.actions.githubusercontent.com。
  • aud:工作流程要求的對象值。請設定 OpenAI,要求此值與工作流程指定的值完全相同,例如 your-wif-audience 或 https://api.openai.com/v1。
  • sub:識別主體的主要字串。GitHub 會根據工作流程的中繼資料組成此字串,例如程式碼庫、分支、標籤、pull request 或環境。
  • repository:執行工作流程的程式碼庫,例如 my-org/my-repo。
  • repository_owner:擁有程式碼庫的組織或使用者,例如 my-org。
  • ref:觸發工作流程的 Git 參照,例如 refs/heads/main 或 refs/tags/v1.0.0。
  • workflow:工作流程宣告。請使用 GitHub 實際傳回的宣告值。例如,如果作業中的工作流程宣告值為 deploy,就使用該值。
  • workflow_ref:工作流程檔案的路徑和 Git 參照,例如 my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main。
  • environment:作業使用的 GitHub 環境名稱,例如 production。只有使用環境的作業才有這項宣告。
  • run_id、run_number、run_attempt 和 job_workflow_ref:用於識別工作流程執行個體和作業,可協助稽核或設定更進階的信任規則。

如需完整的宣告清單和主體格式,請參閱 GitHub 的 OpenID Connect 參考文件。

驗證權杖

設定工作負載身分識別同盟之前,請將 GitHub OIDC 權杖匯出為環境變數 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 的承載資料,不會驗證權杖簽章。請使用本機解碼工具處理正式環境的權杖,避免將這些權杖貼到第三方工具中。切勿將原始 GitHub OIDC 權杖或換得的 OpenAI 存取權杖寫入記錄。

GitHub Actions OIDC 權杖解碼後的內容類似如下:

{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:environment:production",
  "repository": "my-org/my-repo",
  "repository_owner": "my-org",
  "ref": "refs/heads/main",
  "workflow": "deploy",
  "workflow_ref": "my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main",
  "environment": "production",
  "run_id": "1234567890",
  "run_attempt": "1"
}

使用解碼後的承載資料,核對收到的權杖是否符合 OpenAI 中設定的簽發者、對象和對應值。交換權杖前,檢查 iss、aud、repository、ref 和 workflow_ref 宣告,就能發現大多數設定問題。

設定工作負載身分識別同盟

在 OpenAI 中為 GitHub Actions 建立工作負載身分提供者,然後新增服務帳戶對應,指定要信任的 GitHub 工作流程宣告值。

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

設定工作負載身分提供者

  1. 建立工作負載身分提供者。 將名稱設為唯一值,例如 github-actions-prod。在說明中填入 Production GitHub Actions workflows 等描述,方便管理員辨識提供者。

  2. 設定簽發者和對象。 將 OIDC 簽發者網址設為 https://token.actions.githubusercontent.com。將對象設為工作流程要求的確切對象值,例如 your-wif-audience 或 https://api.openai.com/v1。

  3. 使用 GitHub 的 OIDC 探索機制。 請讓使用上傳的 JWKS 驗證權杖選項保持停用。OpenAI 會使用 GitHub 的 OIDC 探索中繼資料和 JWKS 驗證 GitHub 簽發的權杖。

  4. 只有在需要衍生對應屬性時才新增屬性轉換。 對應條件可以直接使用 GitHub 的原始宣告,例如 repository、ref 和 workflow。建立衍生屬性時,儀表板會自動加上 openai. 前置詞。例如,輸入 github_repository 並將運算式設為 assertion.repository,即可建立 openai.github_repository。如果原始權杖中的宣告已帶有 openai. 前置詞,除非已設定相應的轉換,否則系統在比對以 openai. 開頭的對應鍵時會忽略這些宣告。

設定服務帳戶對應

  1. 建立服務帳戶對應。 將名稱設為此工作負載身分提供者中唯一的值,例如 github-actions-main-deploy。在說明中填入 Production deploy workflow on main 等描述,指出哪個工作流程可以使用這項對應。

  2. 新增要求宣告值完全相符的條件。 針對每個必須比對的 GitHub 宣告,各新增一列,填入鍵和值。只有每一列的條件都符合時,OpenAI 才會核發存取權杖。正式環境的部署工作流程可以使用下列條件:

    iss == "https://token.actions.githubusercontent.com"
    aud == "https://api.openai.com/v1"
    repository == "my-org/my-repo"
    ref == "refs/heads/main"
    workflow_ref == "my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main"

    設定高權限對應時,請優先使用 workflow_ref 而非 workflow,因為管理員通常只想信任特定的工作流程檔案路徑和 Git 參照。工作流程可以重新命名,而且多個工作流程檔案可以使用相同的工作流程名稱。

    在對應設定介面中,逐列輸入鍵和值,例如將鍵 repository 的值設為 my-org/my-repo,將鍵 ref 的值設為 refs/heads/main,並將鍵 workflow_ref 的值設為 my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main。如果作業使用 GitHub 環境,請再新增一列,將鍵設為 environment,值設為 production。

    注意: 避免設定範圍過廣的對應。例如,除非該擁有者命名空間下的每個程式碼庫都應能取得新核發的 OpenAI 存取權杖,否則請勿僅以 repository_owner == "my-org" 作為信任條件。

  3. 選擇 OpenAI 目標。 將專案設為目標服務帳戶所屬的 OpenAI 專案。將服務帳戶設為 GitHub 工作流程可以使用的 OpenAI 服務帳戶,例如 github-actions-prod-deploy。

  4. 視需要縮小 API 權限範圍。 選取適當的權限,例如 api.model.request 和 api.vector_store.read,進一步限制透過此對應核發的存取權杖所能執行的操作。如果不需要額外限制工作負載身分識別同盟的授權範圍,請將權限留白。使用該權杖時,仍會以對應的服務帳戶身分取得授權。

在工作流程中使用權杖

設定 OpenAI SDK 用戶端,讓它要求 GitHub OIDC 權杖,並用該權杖換取 OpenAI 核發的存取權杖。

工作流程必須授予 id-token: write 權限,並將工作負載身分識別同盟的設定傳給 SDK 程式碼。SDK 會使用 GitHub 提供給作業的 ACTIONS_ID_TOKEN_REQUEST_URL 和 ACTIONS_ID_TOKEN_REQUEST_TOKEN 環境變數來要求 GitHub OIDC 權杖,再使用換得的 OpenAI 存取權杖驗證 API 要求。

例如,你可以透過以下工作流程執行應用程式碼:

name: deploy

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Run OpenAI SDK code
        env:
          OPENAI_WIF_AUDIENCE: ${{ vars.OPENAI_WIF_AUDIENCE }}
          OPENAI_IDENTITY_PROVIDER_ID: ${{ vars.OPENAI_IDENTITY_PROVIDER_ID }}
          OPENAI_SERVICE_ACCOUNT_ID: ${{ vars.OPENAI_SERVICE_ACCOUNT_ID }}
        run: node --experimental-strip-types ./scripts/call-openai.mts

將 OPENAI_WIF_AUDIENCE、OPENAI_IDENTITY_PROVIDER_ID 和 OPENAI_SERVICE_ACCOUNT_ID 儲存為 GitHub Actions 變數。這些值用來識別提供者和服務帳戶,並非持有者憑證。

以下範例使用自訂的主體權杖提供者初始化 OpenAI 用戶端。提供者會針對已設定的對象要求 GitHub OIDC 權杖,再將其作為工作負載身分識別同盟的主體權杖。

使用 GitHub Actions OIDC 權杖驗證身分
import OpenAI from "openai";

const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;
const audience = process.env.OPENAI_WIF_AUDIENCE;
const requestURL = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;

if (
  !identityProviderId ||
  !serviceAccountId ||
  !audience ||
  !requestURL ||
  !requestToken
) {
  throw new Error(
    "Set OPENAI_IDENTITY_PROVIDER_ID, OPENAI_SERVICE_ACCOUNT_ID, OPENAI_WIF_AUDIENCE, and run inside GitHub Actions with id-token: write"
  );
}

function githubActionsOIDCTokenProvider(
  requestURL: string | URL,
  requestToken: string,
  audience: string
) {
  return {
    tokenType: "jwt" as const,
    getToken: async () => {
      const url = new URL(requestURL);
      url.searchParams.set("audience", audience);

      const response = await fetch(url, {
        headers: { Authorization: `bearer ${requestToken}` },
      });

      if (!response.ok) {
        throw new Error(
          `Failed to request GitHub OIDC token: ${response.status} ${response.statusText}`
        );
      }

      const body = await response.json();
      if (!body.value) {
        throw new Error("GitHub OIDC token response did not include a value.");
      }

      return body.value;
    },
  };
}

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

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

console.log(response.output_text);

GitHub Actions 最佳做法

  • 為正式環境部署啟用環境保護機制。要求工作流程先取得核准或符合分支限制,才能存取正式環境的 OpenAI 資源。
  • 依程式碼庫限制對應範圍。盡可能比對可識別特定程式碼庫的宣告,避免允許組織內所有程式碼庫存取。
  • 依分支或工作流程限制對應範圍。可考慮比對 repository、ref、environment 或 workflow_ref 等宣告,限制核發權杖的條件。
  • 為 CI/CD 和正式環境的工作負載分別使用不同的 OpenAI 服務帳戶。建置管線所需的權限通常與已部署的應用程式不同。
  • 避免授予來自不受信任分支程式碼庫的 pull requests 存取權。這些 pull requests 可能會執行攻擊者控制的程式碼,因此不應取得正式環境的憑證。
  • 使用短效權杖進行交換。GitHub OIDC 權杖用於短暫的身分驗證,請只在需要時交換權杖。
  • 稽核程式碼庫擁有權的變更。程式碼庫移轉、重新命名或權限變更,都可能影響現有對應所依據的安全假設。
  • 優先採用完全相符的宣告比對條件。比對 repository、ref 和 environment 等宣告,避免依賴涵蓋整個組織的信任關係。