For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Hauptnavigation

Föderation von Workload-Identitäten für SPIFFE konfigurieren

Nutze SPIFFE als Identitätsanbieter für Workloads, indem du ein SPIFFE JWT-SVID gegen ein kurzlebiges OpenAI-Zugriffstoken eintauschst. So können Workloads, die von SPIRE oder einem anderen SPIFFE-kompatiblen Identitätsanbieter authentifiziert werden, die OpenAI API aufrufen, ohne langlebige API-Schlüssel zu speichern.

Wenn du Codex verwendest, folge der Anleitung auf dieser Seite, um das JWT-SVID abzurufen und zu prüfen. Konfiguriere anschließend die Workload-Identität für Codex, um das Token in eine Datei zu schreiben und Codex auf diese Datei zu verweisen. Die Dienstkontozuordnung und die SDK-Beispiele auf dieser Seite gelten für die OpenAI API.

OpenAI unterstützt SPIFFE JWT-SVIDs, die sich als JWT-Subject-Token mit Aussteller, Audience, Ablaufzeitpunkt, Ausstellungszeitstempel und einer anhand eines JWKS überprüfbaren Signatur validieren lassen. OpenAI unterstützt keine SPIFFE X.509-SVIDs als Subject-Token für die Föderation von Workload-Identitäten.

Die JWT-SVID-Spezifikation schreibt die Claims sub, aud und exp vor. Damit du ein JWT-SVID mit OpenAI verwenden kannst, muss das Token zusätzlich die Claims iss und iat sowie einen kid-Header enthalten. So kann OpenAI das Token anhand der Konfiguration des Identitätsanbieters für Workloads validieren.

Ein JWT-SVID ist kein OpenID Connect ID-Token. Der SPIRE OIDC Discovery Provider stellt Discovery-Metadaten und JWKS-Schlüssel bereit, damit OpenAI das JWT-SVID validieren kann. Dabei bleibt die SPIFFE-Semantik des Tokens unverändert, und ein OIDC-Anmeldeablauf ist nicht erforderlich.

Die SPIFFE-Terminologie und die Anforderungen an Token findest du in der JWT-SVID-Spezifikation und der Spezifikation der Workload API von SPIFFE.

SPIFFE einrichten

Konfiguriere deinen SPIFFE-Anbieter so, dass er JWT-SVIDs für Workloads ausstellt, die die OpenAI API aufrufen müssen. Diese Anleitung verwendet die SPIRE-Terminologie. Dieselbe OpenAI-Konfiguration gilt jedoch für jeden SPIFFE-kompatiblen Anbieter, der JWT-SVIDs mit Ausstellerangaben und JWKS-Signaturschlüsselmaterial ausgibt, die OpenAI validieren kann.

Dein SPIFFE-Setup muss Folgendes bereitstellen:

  • Eine stabile SPIFFE-ID für die Workload, zum Beispiel spiffe://example.org/ns/production/sa/openai-wif.
  • Eine einzige JWT-SVID-Audience speziell für den Zugriff auf OpenAI, zum Beispiel https://api.openai.com/v1 oder einen anderen frei gewählten opaken Wert.
  • Eine JWT-Aussteller-URL, die zur Validierung durch OpenAI im Claim iss des JWT-SVID enthalten ist.
  • Ein öffentliches JWKS für die JWT-SVID-Signaturschlüssel, entweder über OIDC Discovery oder als hochgeladenes JWKS.
  • Eine Möglichkeit für die Workload, aktuelle JWT-SVIDs von der SPIFFE Workload API abzurufen.

Die Audience ist eine Kennung, die exakt übereinstimmen muss, und nicht unbedingt ein Endpunkt, der das JWT-SVID empfängt. Du kannst https://api.openai.com/v1 oder einen anderen dienstspezifischen Wert verwenden, solange dieser in der Anfrage an die SPIFFE Workload API und in der Anbieterkonfiguration in OpenAI übereinstimmt.

Mache den SPIFFE-Aussteller nach Möglichkeit über deinen SPIRE OIDC Discovery Provider zugänglich. Setze jwt_issuer im SPIRE Server und jwt_issuer im OIDC Discovery Provider auf dieselbe HTTPS-Aussteller-URL, die du in OpenAI konfigurieren wirst.

In der Konfiguration des SPIRE Server:

server {
  trust_domain = "example.org"
  jwt_issuer   = "https://spire-oidc.example.org"
}

In der separaten Konfiguration des SPIRE OIDC Discovery Provider:

# Relevant issuer fields only
domains    = ["spire-oidc.example.org"]
jwt_issuer = "https://spire-oidc.example.org"

Die Konfiguration des OIDC Discovery Provider benötigt außerdem eine Quelle für das Schlüsselmaterial, zum Beispiel server_api, workload_api oder file, sowie einen Mechanismus zur Bereitstellung, etwa ACME, ein TLS-Zertifikat oder einen Unix-Socket. Alle Konfigurationsoptionen findest du in der Dokumentation des SPIRE OIDC Discovery Provider.

Die SPIFFE-Vertrauensdomäne und der JWT-Aussteller sind unterschiedliche Konzepte. In diesem Beispiel ist das Subject des JWT-SVID eine SPIFFE-ID in der Vertrauensdomäne example.org, während der Aussteller die HTTPS-Aussteller-URL ist:

{
  "sub": "spiffe://example.org/ns/production/sa/openai-wif",
  "iss": "https://spire-oidc.example.org"
}

Der SPIRE OIDC Discovery Provider stellt ein OIDC-Discovery-Dokument und einen JWKS-Endpunkt bereit, die OpenAI nutzen kann, wenn Hochgeladenes JWKS zur Tokenüberprüfung verwenden deaktiviert ist.

Wenn OpenAI deinen Discovery-Endpunkt für den Aussteller nicht erreichen kann, verwende stattdessen den Modus mit hochgeladenem JWKS. In diesem Modus vergleicht OpenAI weiterhin den Aussteller des Identitätsanbieters für Workloads mit dem Claim iss des JWT-SVID. Die Signaturen überprüft OpenAI jedoch anhand des JWKS-JSON, das du beim Identitätsanbieter für Workloads speicherst.

Hinweis: Laut SPIFFE-JWT-SVID-Spezifikation ist der JWT-Header kid optional. OpenAI verlangt jedoch, dass JWT-Subject-Token einen kid-Header enthalten, damit OpenAI den Signaturschlüssel aus dem konfigurierten JWKS auswählen kann. Wenn dein SPIFFE-Anbieter kid weglassen kann, konfiguriere ihn so, dass er diesen Header für die Föderation von Workload-Identitäten mit OpenAI einschließt.

Um ein JWT-SVID einer Workload zu prüfen, die die SPIFFE Workload API aufrufen kann, fordere eines für dieselbe Audience an, die du in OpenAI konfigurieren wirst. Führe diesen Befehl im selben Workload-Kontext wie die Anwendung aus, da die Autorisierung durch die Workload API von der Identität des aufrufenden Prozesses abhängt.

TOKEN=$(spire-agent api fetch jwt \
  -socketPath /run/spire/sockets/agent.sock \
  -audience "https://api.openai.com/v1" | sed -n '2p')
export TOKEN

Wenn deine Workload mehr als eine SPIFFE-ID hat, fordere die konkrete Identität an:

TOKEN=$(spire-agent api fetch jwt \
  -socketPath /run/spire/sockets/agent.sock \
  -spiffeID "spiffe://example.org/ns/production/sa/openai-wif" \
  -audience "https://api.openai.com/v1" | sed -n '2p')
export TOKEN

Token überprüfen

Bevor du die Föderation von Workload-Identitäten konfigurierst, exportiere das JWT-SVID als TOKEN. Führe anschließend eines dieser Beispiele lokal aus, um den Header und die Claims zu prüfen:

const parts = process.env.TOKEN?.split(".") ?? [];
if (parts.length !== 3) {
  throw new Error("Expected a compact JWT with three segments");
}

const decode = (segment) => {
  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]));

Jedes Beispiel dekodiert das JWT, ohne die Signatur des Tokens zu überprüfen. Verwende für Token aus dem Produktivbetrieb einen lokalen Decoder und vermeide es, solche Token in Tools von Drittanbietern einzufügen.

Ein dekodiertes SPIFFE JWT-SVID sieht etwa so aus:

{
  "alg": "ES256",
  "kid": "jwt-svid-key-1"
}
{
  "iss": "https://spire-oidc.example.org",
  "aud": ["https://api.openai.com/v1"],
  "sub": "spiffe://example.org/ns/production/sa/openai-wif",
  "iat": 1716235422,
  "exp": 1716235722
}

Vergleiche das empfangene Token in seiner dekodierten Form mit der OpenAI-Konfiguration, bevor du es eintauschst. Prüfe alg und kid im Header sowie iss, aud, sub, iat und exp in der Payload. Der genaue Wert von alg hängt von der Konfiguration der JWT-Signaturschlüssel in deinem SPIRE Server ab.

Föderation von Workload-Identitäten einrichten

Erstelle in OpenAI einen Identitätsanbieter für Workloads für den Aussteller der SPIFFE JWT-SVIDs. Füge anschließend eine Dienstkontozuordnung hinzu, die mit den SPIFFE-IDs übereinstimmt, denen du vertraust.

Identitätsanbieter für Workloads einrichten

  1. Erstelle den Identitätsanbieter für Workloads. Setze Name auf einen eindeutigen Wert, zum Beispiel spiffe-prod. Gib unter Beschreibung einen Text wie Production SPIFFE workloads ein, damit das Administrationsteam den Anbieter leichter identifizieren kann.

  2. Lege Aussteller und Audience fest. Setze OIDC-Aussteller-URL auf den exakten Wert des Claims iss im JWT-SVID, zum Beispiel https://spire-oidc.example.org. Setze Audience auf den Audience-Wert, den du bei der SPIFFE Workload API angefordert hast. In diesem Beispiel lautet der Wert https://api.openai.com/v1.

  3. Wähle die JWKS-Quelle. Lass Hochgeladenes JWKS zur Tokenüberprüfung verwenden deaktiviert, wenn OpenAI deinen SPIRE OIDC Discovery Provider erreichen kann. OpenAI verwendet OIDC Discovery und das dabei ermittelte JWKS, um JWT-SVID-Signaturen zu überprüfen.

    Wenn der Aussteller für OpenAI nicht erreichbar ist, aktiviere Hochgeladenes JWKS zur Tokenüberprüfung verwenden. Trage anschließend unter JWKS-JSON den öffentlichen Schlüsselsatz für die JWT-SVID-Signaturschlüssel ein. Lade das vollständige öffentliche JWKS-Objekt einschließlich des umschließenden keys-Arrays hoch. Es darf kein privates Schlüsselmaterial enthalten.

  4. Füge Attributtransformationen nur hinzu, wenn du abgeleitete Zuordnungsattribute benötigst. Bei einer direkten Zuordnung anhand von sub sind keine Attributtransformationen erforderlich. Verwende sie nur, wenn du einen Zuordnungswert aus einem oder mehreren Token-Claims ableiten musst. Wie Transformationen funktionieren, erfährst du in der Hauptanleitung zur Föderation von Workload-Identitäten.

Dienstkontozuordnung einrichten

  1. Erstelle eine Dienstkontozuordnung. Setze Name auf einen Wert, der innerhalb des Identitätsanbieters für Workloads eindeutig ist, zum Beispiel production-openai-wif. Erläutere unter Beschreibung, welche Workload die Zuordnung nutzen kann, zum Beispiel mit Production SPIFFE workload for OpenAI API access.

  2. Lege den Abgleich der SPIFFE-ID fest. Setze Schlüssel auf sub und Wert auf die SPIFFE-ID der Workload, zum Beispiel spiffe://example.org/ns/production/sa/openai-wif.

    Bevorzuge für privilegierte Workloads den exakten Abgleich der SPIFFE-ID. Verwende ein Platzhalterzeichen am Ende nur dann, wenn sich jede SPIFFE-ID mit diesem Präfix OpenAI-Zugriffstoken ausstellen lassen können soll. Zum Beispiel lässt spiffe://example.org/ns/production/sa/* jeden passenden Dienstkontopfad der Produktionsumgebung zu.

  3. Wähle das OpenAI-Ziel. Setze Projekt auf das OpenAI-Projekt, zu dem das Zieldienstkonto gehört. Setze Dienstkonto auf das OpenAI-Dienstkonto, das die SPIFFE-Workload verwenden darf, zum Beispiel spiffe-prod-openai-wif. Aktiviere Create a new service account in this project, wenn du für diese Zuordnung ein neues Dienstkonto erstellen möchtest, statt ein vorhandenes wiederzuverwenden.

  4. Schränke bei Bedarf die API-Berechtigungen ein. Wähle passende Berechtigungen wie api.model.request und api.vector_store.read, um die über diese Zuordnung ausgestellten Zugriffstoken weiter einzuschränken. Lass die Berechtigungen leer, wenn du keine WIF-spezifische Einschränkung des Berechtigungsumfangs hinzufügen möchtest. Mit dem Token erfolgt die Autorisierung weiterhin als das zugeordnete Dienstkonto.

Token im Code verwenden

Konfiguriere deinen Client für das OpenAI SDK so, dass er ein aktuelles SPIFFE JWT-SVID gegen ein von OpenAI ausgestelltes Zugriffstoken eintauscht.

Die folgenden SDK-Beispiele setzen voraus, dass deine SPIFFE-Integration ein JWT-SVID erneuert und in /var/run/spiffe/openai.jwt schreibt. Stelle sicher, dass nur die Workload die Datei lesen kann. Da JWT-SVIDs kurzlebig sind, musst du die Datei vor Ablauf des Tokens aktualisieren. Alternativ kannst du nach Möglichkeit im Subject-Token-Provider eine sprachspezifische SPIFFE-Bibliothek verwenden, um das JWT-SVID direkt von der SPIFFE Workload API abzurufen. So vermeidest du veraltete Tokendateien.

Setze OPENAI_IDENTITY_PROVIDER_ID und OPENAI_SERVICE_ACCOUNT_ID in der Workload-Umgebung. Die Tokendatei enthält das externe Subject-Token. OPENAI_IDENTITY_PROVIDER_ID identifiziert den Identitätsanbieter für Workloads in OpenAI, und OPENAI_SERVICE_ACCOUNT_ID identifiziert das OpenAI-Zieldienstkonto. OpenAI ermittelt dann anhand der Token-Claims eine passende Zuordnung für diesen Anbieter und dieses Dienstkonto.

Mit einem SPIFFE JWT-SVID authentifizieren
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) {
  return {
    tokenType: "jwt",
    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);

Bewährte Methoden für SPIFFE

  • Verwende JWT-SVIDs für die Föderation von Workload-Identitäten mit OpenAI. X.509-SVIDs eignen sich für Mutual TLS, werden aber vom OpenAI-Endpunkt für den Tokenaustausch nicht akzeptiert.
  • Verwende eine einzige Audience speziell für den Zugriff auf OpenAI. Vermeide zu weit gefasste Audiences wie eine gesamte Vertrauensdomäne oder den Namen einer Umgebung.
  • Gleiche SPIFFE-IDs nach Möglichkeit exakt ab. Verwende Zuordnungen mit Platzhalterzeichen nur für bewusst gemeinsam genutzte Vertrauensgrenzen.
  • Halte die Gültigkeitsdauer von JWT-SVIDs kurz, um das Risiko von Replay-Angriffen mit Bearer-Token zu verringern. OpenAI-Zugriffstoken sind nie länger gültig als das externe Subject-Token, das für den Austausch verwendet wurde.
  • Gehe beim Rotieren von Signaturschlüsseln sorgfältig vor. Veröffentliche während des Rotationszeitraums sowohl die alten als auch die neuen öffentlichen Schlüssel über OIDC Discovery. Alternativ aktualisiere das hochgeladene öffentliche JWKS, bevor du JWT-SVIDs mit einem neuen kid ausstellst.
  • Halte die Uhren des SPIRE Server und der Workloads synchron. Größere Zeitabweichungen können dazu führen, dass ansonsten gültige JWT-SVIDs als noch nicht gültig, zu alt oder abgelaufen abgelehnt werden.
  • Schütze den Socket der SPIFFE Workload API. Ein Prozess, der das JWT-SVID einer Workload abrufen kann, kann versuchen, es gegen Zugriff auf OpenAI einzutauschen.
  • Grenze OpenAI-Dienstkonten entsprechend den Berechtigungsgrenzen deiner Anwendungen und Umgebungen voneinander ab. Verwende kein hoch privilegiertes Dienstkonto gemeinsam für voneinander unabhängige SPIFFE-Workloads.
  • Überwache den Token-Austausch auf Fehler durch Abweichungen bei Aussteller, Audience, Signaturschlüssel und Zuordnung.