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 Idira konfigurieren

Mit Idira Secure Workload Access (SWA) kannst du die OpenAI API aufrufen, ohne einen OpenAI-API-Schlüssel zu speichern. SWA weist deinem Workload eine SPIFFE-ID zu und stellt ein JWT-SVID aus. Dieses signierte Token steht für die Identität deines Workloads. Das OpenAI SDK tauscht das Token gegen ein kurzlebiges OpenAI-Zugriffstoken mit den Berechtigungen des zugeordneten Dienstkontos ein.

Diese Anleitung beschreibt, wie du die OpenAI API konfigurierst. Für Codex führst du die hier beschriebenen Schritte zur Bereitstellung des Tokens aus. Folge anschließend der Anleitung Workload-Identität mit Codex verwenden.

Voraussetzungen

Du benötigst:

  • Eine SWA-Bereitstellung mit einer Vertrauensdomäne und einer Attestierungsrichtlinie, die deinem Workload die erwartete SPIFFE-ID zuweist.
  • Zugriff auf den Socket der Workload API des SWA-Agenten aus deinem Workload heraus.
  • Die Berechtigung, Anbieter für Workload-Identitäten, Dienstkontozuordnungen, Projekte und Dienstkonten in deiner OpenAI-Organisation zu verwalten.
  • Ein OpenAI SDK, das Anmeldedaten für Workload-Identitäten unterstützt.

Richte die SWA-Infrastruktur vollständig ein. Die Voraussetzungen findest du in der Idira-Anleitung zur OpenAI-Integration.

Aussteller und Signaturschlüssel ermitteln

Ermittle für deine Vertrauensdomäne die Werte von jwt.discovery_endpoints.oidc_discovery_url und jwt.discovery_endpoints.jwks_uri. Wo du diese Werte findest, erfährst du in der Idira-Anleitung zur OIDC-Konfiguration.

OpenAI muss das Discovery-Dokument und das JWKS über HTTPS ohne Anmeldedaten abrufen können. Die HTTPS-URL im Claim iss des Tokens gibt den Aussteller an. Die SPIFFE-ID in sub identifiziert deinen Workload.

Wähle für den Zugriff auf OpenAI eine eigene Audience, etwa https://api.openai.com/v1. Verwende denselben Wert, wenn du das JWT-SVID anforderst und den Anbieter in OpenAI konfigurierst. Die Audience gibt an, für welchen Empfänger das Token bestimmt ist. Sie legt den Endpunkt für den Tokenaustausch nicht fest.

SWA signiert standardmäßig mit RS512 und einem 4096-Bit-RSA-Schlüssel. OpenAI akzeptiert diese Kombination bei der JWT-Prüfung. Weitere Signaturoptionen für SWA findest du in den JWT-Anforderungen von Idira.

Dem Workload ein aktuelles JWT-SVID bereitstellen

Installiere spiffe-helper in der Umgebung deines Workloads. Damit kannst du beim SWA-Agenten ein JWT-SVID anfordern und es regelmäßig erneuern lassen. Speichere die folgende Konfiguration als helper.conf. Der Helper schreibt das Token in die Datei /var/run/spiffe/openai.jwt. Diesen Pfad verwenden auch die gemeinsamen SPIFFE-Beispiele für die SDKs.

agent_address = "/tmp/swa-agent/public/api.sock"
cert_dir      = "/var/run/spiffe"
daemon_mode   = true

jwt_svids = [{
  jwt_audience       = "https://api.openai.com/v1"
  jwt_svid_file_name = "openai.jwt"
}]

Führe den Helper in Kubernetes als Sidecar im Pod des Workloads aus. Binde ein gemeinsames emptyDir-Volume im Arbeitsspeicher unter /var/run/spiffe ein. Binde außerdem das Verzeichnis des SWA-Sockets, /tmp/swa-agent/public, in den Sidecar-Container ein. Verwende auf VMs /run/swa-agent/api.sock als Wert für agent_address und lege das Tokenverzeichnis im Arbeitsspeicher ab. Befolge für den Socketzugriff und die Attestierung die Bereitstellungsanleitung von Idira.

Erstelle das Tokenverzeichnis, bevor du den Helper startest, und gib ihm Schreibzugriff darauf. Starte den Helper mit dieser Konfiguration im Sidecar oder im Dienst auf der VM:

spiffe-helper -config helper.conf

Beschränke den Zugriff auf die Tokendatei und den Socket des Agenten auf die Prozesse, die darauf angewiesen sind. Lass den Helper weiterlaufen, damit er das Token vor Ablauf ersetzt.

Wenn es für deine Programmiersprache einen Client für die SPIFFE Workload API gibt, kannst du ein aktuelles JWT-SVID auch direkt im Anbieter für das Subject-Token abrufen. Wie du die Workload API direkt nutzt, erfährst du in der Integrationsanleitung von Idira.

Token prüfen

Lies das Token innerhalb des Workloads in eine Umgebungsvariable für den lokalen Decoder ein:

export TOKEN="$(cat /var/run/spiffe/openai.jwt)"
const parts = process.env.TOKEN?.split(".") ?? [];
if (parts.length !== 3) {
  throw new Error("Expected a compact JWT with three segments");
}

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

Prüfe die folgenden Felder, bevor du den Anbieter in OpenAI erstellst:

Feld Erwarteter Wert
Header alg Der konfigurierte Signaturalgorithmus, etwa RS512.
Header kid Die ID eines Signaturschlüssels im öffentlichen JWKS der Vertrauensdomäne.
iss Die HTTPS-URL des Ausstellers für die Vertrauensdomäne.
sub Die SPIFFE-ID, die diesem Workload zugewiesen wurde.
aud Enthält die Audience, die du für den Zugriff auf OpenAI gewählt hast.
iat und exp Ausstellungs- und Ablaufzeitpunkt des Tokens. Verwende ein Token, das noch gültig ist.

Der Decoder liest die Claims aus, ohne die Signatur zu prüfen. Schreibe das Token nicht in Protokolle und füge es nicht in einen webbasierten Decoder ein. Entferne nach der Prüfung die Umgebungsvariable TOKEN.

Identitätsföderation für Workloads in OpenAI konfigurieren

Anbieter für Workload-Identitäten erstellen

Öffne Organisationseinstellungen > Sicherheit > Anbieter für Workload-Identitäten und erstelle einen Anbieter mit den folgenden Einstellungen:

Einstellung Wert
Name Ein eindeutiger Name, etwa idira-prod.
Beschreibung Die Anwendung und die Umgebung, die diesen Anbieter verwenden.
OIDC-Aussteller-URL Der Wert von iss im JWT-SVID.
Audience Die vom Helper angeforderte Audience, etwa https://api.openai.com/v1.
Hochgeladenes JWKS zur Tokenprüfung verwenden Lass diese Option deaktiviert, um OIDC Discovery zu verwenden.
Attributtransformationen Lass dieses Feld leer, wenn die Zuordnung direkt über sub erfolgt.

Beim Tokenaustausch über die OpenAI API werden abschließende Schrägstriche beim Vergleich der Aussteller-URLs ignoriert. So gelten https://issuer.example.com und https://issuer.example.com/ als identisch. Alle anderen Zeichen müssen übereinstimmen, auch im Schema und im Pfad. Die Audience-Werte müssen exakt übereinstimmen. Übernimm die Aussteller-URL so, wie sie im Token steht, damit deine Konfiguration konsistent bleibt.

Wenn OpenAI das Discovery-Dokument oder das JWKS nicht erreichen kann, folge den allgemeinen Hinweisen zur Anbieterkonfiguration für das Hochladen eines öffentlichen JWKS. Aktualisiere die hochgeladenen Schlüssel, wenn SWA seine Signaturschlüssel wechselt.

SPIFFE-ID einem Dienstkonto zuordnen

  1. Erstelle in der Anbieterkonfiguration eine Dienstkontozuordnung und gib ihr einen Namen, etwa idira-production-workload.
  2. Setze Schlüssel auf sub und Wert auf die exakte SPIFFE-ID aus dem Token des Workloads, etwa spiffe://prod.example.com/k8s-nodegroup/ns/my-namespace/sa/my-service-account.
  3. Wähle das Projekt und das Dienstkonto aus, die der Workload verwenden darf.
  4. Wähle die Berechtigungen aus, die der Workload benötigt, etwa api.model.request für Modellanfragen. Damit kannst du die Zugriffsrechte des Dienstkontos für diesen Workload einschränken, aber nicht erweitern. Lässt du die Berechtigungen leer, gilt keine zusätzliche Einschränkung durch die Identitätsföderation.

Verwende für jede Anwendung und Umgebung ein eigenes Dienstkonto. Gib möglichst die exakte SPIFFE-ID an. Verwende einen Platzhalter am Ende der ID nur dann, wenn alle Identitäten mit diesem Präfix dieselben Zugriffsrechte erhalten sollen. Vermeide überlappende Zuordnungen. Weitere Informationen findest du im Abschnitt Dienstkontozuordnungen für SPIFFE.

Token im Code verwenden

Setze in der Umgebung des Workloads die IDs deines OpenAI-Anbieters und des ausgewählten Dienstkontos:

export OPENAI_IDENTITY_PROVIDER_ID="<workload identity provider ID>"
export OPENAI_SERVICE_ACCOUNT_ID="<service account ID>"

Die folgenden gemeinsamen SPIFFE-Beispiele lesen das Token aus /var/run/spiffe/openai.jwt. Der Anbieter für das Subject-Token gibt das aktuelle Token zurück, sobald das SDK es gegen ein OpenAI-Zugriffstoken eintauschen oder ein OpenAI-Zugriffstoken erneuern muss. SWA und der Helper erneuern das externe JWT-SVID. Das OpenAI SDK verwaltet das OpenAI-Zugriffstoken.

Mit einem von Idira ausgestellten 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: string) {
  return {
    tokenType: "jwt" as const,
    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);

Konfiguration prüfen und Fehler beheben

Führe das Beispiel innerhalb des attestierten Workloads aus. Dabei darf OPENAI_API_KEY nicht gesetzt sein. Bei einer erfolgreichen Anfrage gibt das Beispiel die Antwort des Modells aus. Prüfe, ob Anfragen weiterhin erfolgreich sind, nachdem der Helper das JWT-SVID ersetzt und das SDK sein OpenAI-Zugriffstoken erneuert hat.

Symptom Was du prüfen solltest
Der Helper erhält keine Identität Prüfe, ob der Workload die SWA-Attestierungsrichtlinie erfüllt und auf den Socket des Agenten zugreifen kann. Führe diese Prüfungen im Kontext des Workloads aus.
Die Tokendatei fehlt, ist leer oder enthält ein abgelaufenes Token Prüfe, ob der Helper läuft, ob Helper und Workload dasselbe Volume und denselben Dateipfad verwenden und ob der Workload die Datei lesen kann. Halte die Systemuhren der Hosts synchron.
Die Tokenprüfung schlägt fehl Prüfe iss, aud, kid und den Ablaufzeitpunkt des Tokens. Prüfe außerdem, ob das Discovery-Dokument und das JWKS erreichbar sind. Beachte beim Vergleich der Aussteller-URLs die oben beschriebene Regel.
Keine Dienstkontozuordnung passt Prüfe die Anbieter-ID, die Dienstkonto-ID, die aktivierte Zuordnung und den exakten Wert von sub.
Mehrere Zuordnungen passen Grenze überlappende Zuordnungen ein oder deaktiviere sie, sodass genau eine aktivierte Zuordnung passt.
Der Tokenaustausch gelingt, aber die API lehnt die Anfrage ab Prüfe das Projekt und die Berechtigungen des zugeordneten Dienstkontos sowie die geltenden Richtlinien für den API-Zugriff.

Hinweise zur Diagnose von Problemen mit der SWA-Bereitstellung findest du in der Idira-Anleitung zur Fehlerbehebung bei der Integration.