Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Identitätsföderation für Workloads mit GitHub Actions konfigurieren

Nutze GitHub Actions als Identitätsanbieter für Workloads, indem du ein von GitHub ausgestelltes OIDC-Token gegen ein kurzlebiges OpenAI-Zugriffstoken eintauschst. So können sich Workflows bei der OpenAI-API authentifizieren, ohne dass du einen langlebigen API-Schlüssel in den GitHub-Secrets speichern musst.

GitHub kann für einen Workflow-Job ein signiertes OIDC-JWT ausstellen, wenn der Job die Berechtigung id-token: write hat und ein Identitätstoken anfordert. OpenAI prüft Aussteller, Audience und Signatur des Tokens sowie die Attribute für die Zuordnung, bevor es ein OpenAI-Zugriffstoken ausstellt.

GitHub Actions einrichten

Gib dem Workflow oder Job die Berechtigung, ein OIDC-Token von GitHub anzufordern:

permissions:
  id-token: write
  contents: read

Mit der Berechtigung id-token: write kann der Job ein OIDC-JWT anfordern. Der Job erhält dadurch keinen Schreibzugriff auf die Inhalte des Repositorys. Die Berechtigung contents: read benötigt actions/checkout.

Fordere das Token mit genau der Audience an, die du in OpenAI für deinen Identitätsanbieter für Workloads konfiguriert hast. Eigene JavaScript-Actions können core.getIDToken("your-wif-audience") aufrufen. In Shell-Schritten kannst du die OIDC-Anfrage-URL von GitHub direkt aufrufen. Enthält der Audience-Wert reservierte URL-Zeichen, wie im Beispiel https://api.openai.com/v1, solltest du ihn URL-kodieren, bevor du ihn an die Anfrage-URL anhängst:

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

Zu den wichtigsten OIDC-Claims von GitHub gehören:

  • iss: Der Aussteller des Tokens. Bei GitHub Actions ist das https://token.actions.githubusercontent.com.
  • aud: Der Audience-Wert, den der Workflow anfordert. Konfiguriere OpenAI so, dass genau der angeforderte Wert erforderlich ist, etwa your-wif-audience oder https://api.openai.com/v1.
  • sub: Die zentrale Zeichenfolge zur Identifikation des Subjekts. GitHub setzt sie aus Workflow-Metadaten wie Repository, Branch, Tag, Pull Request oder Umgebung zusammen.
  • repository: Das Repository, in dem der Workflow läuft, etwa my-org/my-repo.
  • repository_owner: Die Organisation oder Person, der das Repository gehört, etwa my-org.
  • ref: Die Git-Referenz, die den Workflow ausgelöst hat, etwa refs/heads/main oder refs/tags/v1.0.0.
  • workflow: Der Workflow-Claim. Verwende den Wert, den GitHub tatsächlich ausgibt, etwa deploy, wenn der Claim in deinem Job diesen Wert hat.
  • workflow_ref: Der Pfad zur Workflow-Datei und die zugehörige Git-Referenz, etwa my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main.
  • environment: Der Name der GitHub-Umgebung, etwa production, sofern der Job eine Umgebung verwendet.
  • run_id, run_number, run_attempt und job_workflow_ref: Kennungen für Workflow-Ausführungen und Jobs, die bei Audits oder komplexeren Vertrauensregeln helfen können.

Die vollständige Liste der Claims und die Formate für das Subjekt findest du in der OpenID-Connect-Referenz von GitHub.

Token überprüfen

Bevor du die Identitätsföderation für Workloads konfigurierst, exportiere das OIDC-Token von GitHub als TOKEN. Führe anschließend dieses Skript auf dem Workflow-Runner aus, um dir die Claims anzusehen:

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);

Dieser Befehl dekodiert die JWT-Payload, ohne die Signatur des Tokens zu prüfen. Dekodiere Tokens aus dem Produktivbetrieb lokal und vermeide es, sie in Tools von Drittanbietern einzufügen. Schreibe weder das OIDC-Token von GitHub im Klartext noch das beim Austausch erhaltene OpenAI-Zugriffstoken in ein Log.

Ein dekodiertes OIDC-Token von GitHub Actions sieht etwa so aus:

{
  "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"
}

Vergleiche Aussteller, Audience und Zuordnungswerte in der dekodierten Payload des erhaltenen Tokens mit den Werten, die du in OpenAI konfiguriert hast. Die meisten Konfigurationsfehler erkennst du schon vor dem Tokenaustausch an den Claims iss, aud, repository, ref und workflow_ref.

Identitätsföderation für Workloads einrichten

Erstelle in OpenAI einen Identitätsanbieter für Workloads aus GitHub Actions. Füge anschließend eine Dienstkontozuordnung hinzu, die zu den Claims der GitHub-Workflows passt, denen du vertraust.

Konfiguriere zuerst den Identitätsanbieter für Workloads und erstelle anschließend die Dienstkontozuordnung.

Identitätsanbieter für Workloads einrichten

  1. Erstelle den Identitätsanbieter für Workloads. Gib unter Name einen eindeutigen Wert ein, etwa github-actions-prod. Trage unter Beschreibung beispielsweise Production GitHub Actions workflows ein, damit das Administrationsteam den Anbieter leicht erkennt.

  2. Lege Aussteller und Audience fest. Gib unter URL des OIDC-Ausstellers den Wert https://token.actions.githubusercontent.com ein. Trage unter Audience genau den Wert ein, den dein Workflow anfordert, etwa your-wif-audience oder https://api.openai.com/v1.

  3. Nutze die OIDC-Discovery von GitHub. Lass Hochgeladene JWKS zur Tokenprüfung verwenden deaktiviert. OpenAI prüft das von GitHub signierte Token anhand der OIDC-Discovery-Metadaten und des JWKS von GitHub.

  4. Füge Attributtransformationen nur hinzu, wenn du abgeleitete Attribute für die Zuordnung benötigst. Unveränderte GitHub-Claims wie repository, ref und workflow kannst du direkt in den Zuordnungsbedingungen verwenden. Bei abgeleiteten Attributen fügt das Dashboard automatisch das Präfix openai. hinzu. Gib beispielsweise github_repository mit dem Ausdruck assertion.repository ein, um openai.github_repository zu erstellen. Unveränderte Token-Claims, deren Namen bereits mit openai. beginnen, berücksichtigt OpenAI für Zuordnungsschlüssel mit dem Präfix openai. nur dann, wenn eine passende Transformation konfiguriert ist.

Dienstkontozuordnung einrichten

  1. Erstelle eine Dienstkontozuordnung. Gib unter Name einen Wert ein, der innerhalb des Identitätsanbieters für Workloads eindeutig ist, etwa github-actions-main-deploy. Gib unter Beschreibung an, welcher Workflow die Zuordnung verwenden kann, etwa Production deploy workflow on main.

  2. Lege Bedingungen fest, die eine exakte Übereinstimmung der Claims verlangen. Füge für jeden zu prüfenden GitHub-Claim eine Zeile mit Schlüssel und Wert hinzu. OpenAI stellt nur dann ein Zugriffstoken aus, wenn die Bedingungen in allen konfigurierten Zeilen erfüllt sind. Für einen Workflow, der deine Anwendung in der Produktionsumgebung bereitstellt, kannst du beispielsweise folgende Bedingungen verwenden:

    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"

    Verwende für Zuordnungen mit weitreichenden Berechtigungen vorzugsweise workflow_ref statt workflow. In der Regel möchte das Administrationsteam nur einer Workflow-Datei unter einem bestimmten Pfad und einer bestimmten Git-Referenz vertrauen. Workflow-Namen lassen sich ändern, und mehrere Workflow-Dateien können denselben Namen haben.

    Gib die Bedingungen in der Oberfläche für die Zuordnung jeweils als Schlüssel-Wert-Paar ein, etwa Schlüssel repository mit Wert my-org/my-repo, Schlüssel ref mit Wert refs/heads/main und Schlüssel workflow_ref mit Wert my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main. Wenn der Job eine GitHub-Umgebung verwendet, füge auch Schlüssel environment mit Wert production hinzu.

    Achtung: Vermeide zu weit gefasste Zuordnungen. Verwende beispielsweise repository_owner == "my-org" nur dann als einzige Bedingung, wenn jedes Repository in diesem Namensraum OpenAI-Zugriffstokens erhalten darf.

  3. Wähle das Ziel in OpenAI aus. Wähle unter Projekt das OpenAI-Projekt aus, zu dem das Zieldienstkonto gehört. Wähle unter Dienstkonto das OpenAI-Dienstkonto aus, das der GitHub-Workflow verwenden darf, etwa github-actions-prod-deploy.

  4. Schränke die API-Berechtigungen bei Bedarf weiter ein. Wähle unter Berechtigungen passende Einträge wie api.model.request und api.vector_store.read aus, um die Zugriffsrechte der über diese Zuordnung ausgestellten Tokens weiter einzuschränken. Lass das Feld leer, wenn du den Geltungsbereich nicht zusätzlich für WIF einschränken möchtest. Das Token gewährt weiterhin Zugriff mit den Rechten des zugeordneten Dienstkontos.

Token in einem Workflow verwenden

Konfiguriere deinen OpenAI-SDK-Client so, dass er ein OIDC-Token von GitHub anfordert und es gegen ein von OpenAI ausgestelltes Zugriffstoken eintauscht.

Der Workflow muss die Berechtigung id-token: write erteilen und die Einstellungen für die Identitätsföderation von Workloads an den SDK-Code übergeben. Das SDK fordert das OIDC-Token von GitHub mithilfe der Umgebungsvariablen ACTIONS_ID_TOKEN_REQUEST_URL und ACTIONS_ID_TOKEN_REQUEST_TOKEN an, die GitHub dem Job bereitstellt. Anschließend authentifiziert es API-Anfragen mit dem beim Austausch erhaltenen OpenAI-Zugriffstoken.

Du kannst deinen Anwendungscode beispielsweise in folgendem Workflow ausführen:

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

Speichere OPENAI_WIF_AUDIENCE, OPENAI_IDENTITY_PROVIDER_ID und OPENAI_SERVICE_ACCOUNT_ID als Variablen in GitHub Actions. Sie identifizieren den Anbieter und das Dienstkonto. Ihr Besitz allein berechtigt nicht zum Zugriff.

Die folgenden Beispiele initialisieren einen OpenAI-Client mit einem eigenen Anbieter für Subjekttokens. Der Anbieter fordert für die konfigurierte Audience ein OIDC-Token von GitHub an und verwendet es als Subjekttoken für die Identitätsföderation von Workloads.

Mit einem OIDC-Token von GitHub Actions authentifizieren
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);

Bewährte Vorgehensweisen für GitHub Actions

  • Nutze die Schutzregeln der Umgebung für Bereitstellungen im Produktivbetrieb. Verlange eine Genehmigung oder beschränke den Zugriff auf bestimmte Branches, bevor Workflows auf OpenAI-Ressourcen für den Produktivbetrieb zugreifen dürfen.
  • Beschränke Zuordnungen auf bestimmte Repositorys. Prüfe nach Möglichkeit Repository-spezifische Claims, statt allen Repositorys einer Organisation Zugriff zu gewähren.
  • Beschränke Zuordnungen auf bestimmte Branches oder Workflows. Prüfe, ob du die Tokenausstellung anhand von Claims wie repository, ref, environment oder workflow_ref einschränken kannst.
  • Verwende getrennte OpenAI-Dienstkonten für CI/CD und Produktionsworkloads. Build-Pipelines benötigen häufig andere Berechtigungen als die bereitgestellten Anwendungen.
  • Vermeide es, Pull Requests aus nicht vertrauenswürdigen Forks Zugriff zu gewähren. Solche Pull Requests können Code ausführen, den Angreifende kontrollieren, und sollten keine Zugangsdaten für die Produktionsumgebung erhalten.
  • Tausche Tokens erst bei Bedarf aus. OIDC-Tokens von GitHub sind für die kurzzeitige Authentifizierung vorgesehen.
  • Prüfe Änderungen an den Eigentumsverhältnissen von Repositorys. Wenn ein Repository übertragen oder umbenannt wird oder sich Berechtigungen ändern, können die Sicherheitsannahmen bestehender Zuordnungen ihre Gültigkeit verlieren.
  • Prüfe Claims vorzugsweise auf exakte Übereinstimmung. Vergleiche Claims wie repository, ref und environment mit den erwarteten Werten, statt dich auf organisationsweite Vertrauensbeziehungen zu verlassen.