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

Workload Identity Federation für Google Cloud konfigurieren

Du kannst Google Cloud in zwei Szenarien als Identitätsanbieter für deine Workloads verwenden:

  • Google Workload Identity: Tausche ein von Google signiertes OIDC-Token, das für ein zugewiesenes Google-Dienstkonto ausgestellt wurde, gegen ein kurzlebiges OpenAI-Zugriffstoken ein.
  • Google Kubernetes Engine: Tausche ein projiziertes GKE-Dienstkontotoken gegen ein kurzlebiges OpenAI-Zugriffstoken ein.

Google Workload Identity

Workloads in Google Cloud können beim Google-Metadatenserver signierte OIDC-Identitätstoken anfordern, ohne langlebige Dienstkontoschlüssel zu speichern. Bei der Workload Identity Federation mit OpenAI dient das Google-Identitätstoken als Subject-Token. OpenAI prüft es, bevor es ein OpenAI-Zugriffstoken ausstellt. Dieses Verfahren funktioniert auf Compute Engine und Cloud Run, bei GKE-Workloads mit zugewiesenen Google-Dienstkonten sowie in anderen von Google verwalteten Laufzeitumgebungen, die den Identitätsendpunkt des Metadatenservers bereitstellen.

Google Workload Identity einrichten

Erstelle ein Google-Dienstkonto für den Workload, der die OpenAI API aufrufen soll. Alle Schritte findest du in der Google-Anleitung zum Erstellen von Dienstkonten.

Mit der Google Cloud CLI erstellst du ein Dienstkonto zum Beispiel so:

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

Weise das Dienstkonto beim Erstellen der Compute Engine-VM zu oder weise es der Google Cloud-Ressource zu, auf der deine Anwendung läuft. Die Ressource muss den Google-Metadatenserver zur Laufzeit aufrufen können. Weitere Informationen zur VM-Konfiguration findest du in der Google-Anleitung zum Erstellen einer VM mit einem selbst verwalteten Dienstkonto.

Erstelle für dieses Verfahren keine Dienstkontoschlüssel und lade auch keine herunter. Der Workload fordert mit dem zugewiesenen Dienstkonto beim Metadatenserver ein kurzlebiges OIDC-Token an.

Google-Identitätstoken abrufen

Fordere auf der Google Cloud-Ressource, der das Dienstkonto zugewiesen ist, beim Metadatenserver ein OIDC-Identitätstoken für die konfigurierte Audience an. Dieses Token dient als Subject-Token, das OpenAI gegen ein von OpenAI ausgestelltes Zugriffstoken eintauscht.

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

Der Metadatenserver gibt ein von Google signiertes JWT zurück. Weitere Informationen zum Identitätsendpunkt des Metadatenservers findest du in der Google-Anleitung zum Prüfen der VM-Identität.

Token prüfen

Bevor du Workload Identity Federation konfigurierst, exportiere das Google-Identitätstoken als TOKEN. Führe dann das folgende Skript lokal 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);

Der Befehl dekodiert die JWT-Payload, ohne die Signatur des Tokens zu prüfen. Verwende für Token aus dem Produktivbetrieb einen lokalen Decoder und füge diese Token nicht in Tools von Drittanbietern ein.

Die dekodierte Payload eines Identitätstokens vom Google-Metadatenserver sieht etwa so aus:

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

Vergleiche anhand der dekodierten Payload die Werte im erhaltenen Token mit dem Aussteller, der Audience und den Zuordnungswerten, die du bei OpenAI konfiguriert hast. Die meisten Konfigurationsfehler erkennst du bereits vor dem Tokenaustausch an den Claims iss, aud, email und sub.

Workload Identity Federation einrichten

Erstelle bei OpenAI einen Identitätsanbieter für von Google ausgestellte Identitätstoken. Füge dann eine Dienstkontozuordnung hinzu, deren Kriterien mit stabilen Claims im Token übereinstimmen.

Konfiguriere zuerst den Identitätsanbieter und erstelle anschließend die Dienstkontozuordnung.

Identitätsanbieter für Workloads einrichten

  1. Erstelle den Identitätsanbieter. Gib unter Name einen eindeutigen Wert ein, etwa google-workload-identity-prod. Wähle eine Beschreibung wie Production Google Cloud workloads, damit das Administrationsteam den Anbieter leicht erkennt.

  2. Lege Aussteller und Audience fest. Gib als OIDC-Aussteller-URL https://accounts.google.com ein. Trage unter Audience den benutzerdefinierten Wert ein, für den dein Workload beim Google-Metadatenserver ein Token anfordert, etwa https://api.openai.com/v1. Dieser Wert muss mit dem Claim aud im Token übereinstimmen.

  3. Verwende die OIDC-Discovery von Google. Lass die Option Hochgeladene JWKS zur Tokenprüfung verwenden deaktiviert. OpenAI prüft das von Google signierte Identitätstoken anhand der OIDC-Discovery-Metadaten und des JWKS von Google.

  4. Füge Attributtransformationen hinzu, wenn du abgeleitete Attribute für die Zuordnung brauchst. Gib beispielsweise subject mit dem Ausdruck assertion.sub ein, um openai.subject aus dem Subject-Claim abzuleiten. Das Dashboard ergänzt das Präfix openai. automatisch. Beginnt ein Claim im ursprünglichen Token bereits mit openai., ignoriert OpenAI ihn bei Zuordnungsschlüsseln mit dem Präfix openai., sofern du keine passende Transformation konfiguriert hast.

Dienstkontozuordnung einrichten

  1. Erstelle eine Dienstkontozuordnung. Gib unter Name einen Wert ein, der innerhalb des Identitätsanbieters eindeutig ist, etwa compute-openai-wif. Gib in der Beschreibung an, welcher Workload die Zuordnung verwenden darf, etwa Production Compute Engine OpenAI API workload.

  2. Verwende stabile Claims des Google-Dienstkontos als Zuordnungskriterien. Füge für jeden Claim, der übereinstimmen muss, eine Zeile mit Schlüssel und Wert hinzu. Verwende sub als primäres Kriterium für die Zuordnung der Identität, da dieser Wert stabil und eindeutig ist. Für eine besser lesbare Zuordnung kannst du zusätzlich email abgleichen.

  3. Wähle das Ziel bei 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 Google Cloud-Workload verwenden darf, etwa google-workload-identity-prod-openai-wif.

  4. Schränke die API-Berechtigungen bei Bedarf ein. Wähle passende Berechtigungen wie api.model.request und api.vector_store.read, um den Zugriff für Token aus dieser Zuordnung weiter einzuschränken. Lass das Feld leer, wenn du den Berechtigungsumfang für WIF nicht zusätzlich einschränken möchtest. Für das Token gelten weiterhin die Berechtigungen des zugeordneten Dienstkontos.

Token im Code verwenden

Konfiguriere deinen OpenAI SDK-Client so, dass er beim Metadatenserver ein Google-Identitätstoken anfordert und es gegen ein von OpenAI ausgestelltes Zugriffstoken eintauscht.

Setze OPENAI_WIF_AUDIENCE auf die benutzerdefinierte Audience, die du beim Identitätsanbieter für Workloads konfiguriert hast. Das SDK fordert für diese Audience ein Google-Identitätstoken an, tauscht es gegen ein von OpenAI ausgestelltes Zugriffstoken ein und authentifiziert damit API-Anfragen.

Mit einem Identitätstoken vom Google-Metadatenserver authentifizieren
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);

Empfehlungen für Google Cloud

  • Verwende für jeden Workload ein eigenes Google-Dienstkonto. Vermeide es, dass voneinander unabhängige Dienste oder Umgebungen dasselbe Dienstkonto nutzen.
  • Verwende Verfahren mit Workload-Identitäten anstelle langlebiger Dienstkontoschlüssel. Wenn ein Workload Identitätstoken vom Metadatenserver oder GKE Workload Identity nutzen kann, vermeide die Verteilung und Rotation von JSON-Schlüsseldateien.
  • Beschränke jede Identität auf den kleinstmöglichen, praktisch sinnvollen Teil des Workloads. Eigene Dienstkonten für einzelne Anwendungen erleichtern Audits und helfen dir, jeder Anwendung nur die nötigen Zugriffsrechte zu geben.
  • Wähle die Attribute für Zuordnungen sorgfältig aus. Verwende nach Möglichkeit stabile Kennungen wie den Subject-Claim eines Dienstkontos anstelle veränderlicher Metadaten.
  • Trenne Projekte für den Produktivbetrieb von Projekten für andere Umgebungen. Getrennte Projekte verringern das Risiko, Berechtigungen versehentlich projektübergreifend zu vergeben, und erleichtern Audits.
  • Vergib nur die nötigen IAM-Berechtigungen. Beschränke die Berechtigungen der Google-Identität auf das, was der Workload benötigt.
  • Überwache die Nutzung der Dienstkonten. Unerwartete Tokenaustauschvorgänge können auf Abweichungen von der vorgesehenen Konfiguration oder auf kompromittierte Workloads hindeuten.