Um SPIFFE als Identitätsanbieter für Workloads zu nutzen, tausche ein SPIFFE-JWT-SVID gegen ein kurzlebiges OpenAI-Zugriffstoken ein. So können Workloads, die sich über SPIRE oder einen anderen SPIFFE-kompatiblen Identitätsanbieter authentifizieren, die OpenAI API aufrufen, ohne langlebige API-Schlüssel zu speichern.
Wenn du Idira Secure Workload Access verwendest, folge der Setup-Anleitung für Idira, um den Agenten zu konfigurieren und die Token-Bereitstellung einzurichten.
OpenAI unterstützt SPIFFE-JWT-SVIDs, die sich als JWT-Subject-Tokens validieren lassen. Sie müssen den Aussteller, die Audience, den Ablaufzeitpunkt und den Ausstellungszeitpunkt angeben. Ihre Signatur muss sich anhand eines JWKS prüfen lassen. SPIFFE-X.509-SVIDs unterstützt OpenAI nicht als Subject-Tokens für die Workload-Identitätsföderation.
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 das Header-Feld kid 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, mit denen OpenAI das JWT-SVID validieren kann. Die Bedeutung des Tokens nach der SPIFFE-Spezifikation bleibt dabei erhalten. Eine Anmeldung über OIDC ist dafür nicht erforderlich.
Die SPIFFE-Terminologie und die Anforderungen an Tokens 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 Begriffe aus SPIRE. Für andere SPIFFE-kompatible Anbieter gilt dieselbe OpenAI-Konfiguration, sofern OpenAI den Aussteller ihrer JWT-SVIDs validieren und die Signaturen anhand der Schlüssel im JWKS prüfen kann.
Dein SPIFFE-Setup muss Folgendes bereitstellen:
- Eine stabile SPIFFE-ID für den Workload, zum Beispiel
spiffe://example.org/ns/production/sa/openai-wif. - Eine einzige JWT-SVID-Audience, die ausschließlich für den Zugriff auf OpenAI vorgesehen ist, zum Beispiel
https://api.openai.com/v1oder ein anderer frei gewählter, opaker Wert. - Eine URL des JWT-Ausstellers, die OpenAI zur Validierung im Claim
issdes JWT-SVID findet. - Ein öffentliches JWKS für die JWT-SVID-Signaturschlüssel, das du über OIDC Discovery oder per Upload bereitstellst.
- Eine Möglichkeit für den Workload, aktuelle JWT-SVIDs über die SPIFFE Workload API abzurufen.
Die Audience ist eine Kennung, deren Wert exakt übereinstimmen muss. Sie muss keinen Endpunkt bezeichnen, der das JWT-SVID empfängt. Du kannst https://api.openai.com/v1 oder einen anderen dienstspezifischen Wert verwenden, solange du in der Anfrage an die SPIFFE Workload API und in der Anbieterkonfiguration bei OpenAI denselben Wert angibst.
Mache den SPIFFE-Aussteller nach Möglichkeit über deinen SPIRE OIDC Discovery Provider erreichbar. Setze jwt_issuer in der Konfiguration des SPIRE Servers und jwt_issuer in der Konfiguration des OIDC Discovery Providers auf dieselbe HTTPS-URL des Ausstellers, die du bei OpenAI angeben wirst.
In der Konfiguration des SPIRE Servers:
server {
trust_domain = "example.org"
jwt_issuer = "https://spire-oidc.example.org"
}
In der separaten Konfiguration des SPIRE OIDC Discovery Providers:
# Relevant issuer fields only
domains = ["spire-oidc.example.org"]
jwt_issuer = "https://spire-oidc.example.org"
Gib in der Konfiguration des OIDC Discovery Providers außerdem eine Quelle für das Schlüsselmaterial an, etwa server_api, workload_api oder file. Lege auch fest, wie der Provider seinen Dienst bereitstellt, etwa mit ACME, einem TLS-Zertifikat oder über einen Unix-Socket. Alle Konfigurationsoptionen findest du in der Dokumentation zum SPIRE OIDC Discovery Provider.
Die SPIFFE-Vertrauensdomäne und der JWT-Aussteller haben unterschiedliche Funktionen. In diesem Beispiel ist das Subject des JWT-SVID eine SPIFFE-ID in der Vertrauensdomäne example.org. Den Aussteller identifiziert seine HTTPS-URL:
{
"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. OpenAI kann beide nutzen, wenn die Option Hochgeladenes JWKS zur Token-Prüfung verwenden deaktiviert ist.
Wenn OpenAI den Discovery-Endpunkt deines Ausstellers nicht erreichen kann, verwende ein hochgeladenes JWKS. In diesem Modus vergleicht OpenAI weiterhin den beim Identitätsanbieter für Workloads konfigurierten Aussteller mit dem Claim iss des JWT-SVID. Die Signatur prüft OpenAI anhand des JWKS, das du im JSON-Format beim Identitätsanbieter hinterlegst.
Hinweis: Laut SPIFFE-JWT-SVID-Spezifikation ist das JWT-Header-Feld
kidoptional. OpenAI benötigt jedoch in jedem JWT-Subject-Token das Header-Feldkid, um den Signaturschlüssel aus dem konfigurierten JWKS auszuwählen. Falls dein SPIFFE-Anbieterkidweglassen kann, konfiguriere ihn so, dass er das Feld für die Workload-Identitätsföderation mit OpenAI immer einfügt.
Um ein JWT-SVID aus einem Workload zu prüfen, der die SPIFFE Workload API aufrufen kann, fordere ein Token für dieselbe Audience an, die du bei OpenAI konfigurieren wirst. Führe diesen Befehl im selben Workload-Kontext wie die Anwendung aus, da die Workload API den Zugriff anhand der Identität des aufrufenden Prozesses autorisiert.
TOKEN=$(spire-agent api fetch jwt \
-socketPath /run/spire/sockets/agent.sock \
-audience "https://api.openai.com/v1" | sed -n '2p')
export TOKEN
Wenn dein Workload mehrere SPIFFE-IDs hat, gib bei der Anfrage die gewünschte 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 prüfen
Bevor du die Workload-Identitätsföderation konfigurierst, exportiere das JWT-SVID als TOKEN. Führe dann eines der folgenden Beispiele lokal aus, um dir den Header und die Claims anzusehen:
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]));Jedes Beispiel dekodiert das JWT, ohne die Token-Signatur zu prüfen. Verwende für Tokens aus dem Produktivbetrieb einen lokalen Decoder und vermeide es, diese Tokens 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 die dekodierten Werte des empfangenen Tokens mit der OpenAI-Konfiguration, bevor du das Token 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 davon ab, wie du den JWT-Signaturschlüssel auf deinem SPIRE Server konfiguriert hast.
Workload-Identitätsföderation einrichten
Erstelle bei OpenAI einen Identitätsanbieter für Workloads, der dem Aussteller der SPIFFE-JWT-SVIDs entspricht. Füge anschließend eine Dienstkontozuordnung für die SPIFFE-IDs hinzu, denen du vertraust.
Identitätsanbieter für Workloads einrichten
-
Erstelle den Identitätsanbieter für Workloads. Gib unter Name einen eindeutigen Wert ein, zum Beispiel
spiffe-prod. Trage unter Beschreibung einen Text wieProduction SPIFFE workloadsein, damit das Administrationsteam den Anbieter zuordnen kann. -
Lege Aussteller und Audience fest. Trage unter URL des OIDC-Ausstellers exakt den Wert aus dem Claim
issdes JWT-SVID ein, zum Beispielhttps://spire-oidc.example.org. Gib unter Audience denselben Wert an, den du beim Abruf über die SPIFFE Workload API angefordert hast. In diesem Beispiel ist dashttps://api.openai.com/v1. -
Wähle die JWKS-Quelle. Lass Hochgeladenes JWKS zur Token-Prüfung verwenden deaktiviert, wenn OpenAI deinen SPIRE OIDC Discovery Provider erreichen kann. OpenAI ermittelt das JWKS über OIDC Discovery und prüft damit die JWT-SVID-Signaturen.
Wenn OpenAI den Aussteller nicht erreichen kann, aktiviere Hochgeladenes JWKS zur Token-Prüfung verwenden. Hinterlege dann unter JWKS-JSON die öffentlichen Schlüssel, mit denen sich die JWT-SVID-Signaturen prüfen lassen. Lade das vollständige öffentliche JWKS-Objekt einschließlich des Arrays
keyshoch, das die Schlüssel enthält. Lade kein privates Schlüsselmaterial hoch. -
Füge Attributtransformationen nur hinzu, wenn du für die Zuordnung abgeleitete Attribute brauchst. Wenn du die Zuordnung direkt anhand von
subvornimmst, sind keine Attributtransformationen nötig. Verwende sie nur, wenn du einen Wert für die Zuordnung aus einem oder mehreren Token-Claims ableiten musst. Wie die Transformationen funktionieren, erfährst du im Leitfaden zur Workload-Identitätsföderation.
Dienstkontozuordnung einrichten
-
Erstelle eine Dienstkontozuordnung. Gib unter Name einen Wert ein, der innerhalb des Identitätsanbieters für Workloads eindeutig ist, zum Beispiel
production-openai-wif. Erläutere unter Beschreibung, welcher Workload die Zuordnung verwenden kann, zum Beispiel mitProduction SPIFFE workload for OpenAI API access. -
Gleiche die SPIFFE-ID ab. Gib unter Schlüssel den Wert
subund unter Wert die SPIFFE-ID des Workloads ein, zum Beispielspiffe://example.org/ns/production/sa/openai-wif.Bevorzuge bei privilegierten Workloads eine exakte Übereinstimmung der SPIFFE-ID. Verwende einen Platzhalter am Ende nur, wenn sich für jede SPIFFE-ID mit diesem Präfix OpenAI-Zugriffstokens ausstellen lassen sollen. Zum Beispiel lässt
spiffe://example.org/ns/production/sa/*jeden passenden Dienstkontopfad in der Produktionsumgebung zu. -
Wähle das Ziel bei OpenAI. Wähle unter Projekt das OpenAI-Projekt aus, zu dem das Zieldienstkonto gehört. Wähle unter Dienstkonto das OpenAI-Dienstkonto aus, das der SPIFFE-Workload verwenden darf, zum Beispiel
spiffe-prod-openai-wif. AktiviereCreate a new service account in this project, wenn du für diese Zuordnung ein neues Dienstkonto erstellen möchtest, statt ein vorhandenes zu verwenden. -
Schränke die API-Berechtigungen bei Bedarf ein. Wähle unter Berechtigungen passende Werte wie
api.model.requestundapi.vector_store.read, um den Zugriff der über diese Zuordnung ausgestellten Tokens weiter einzuschränken. Lass das Feld leer, wenn du den Geltungsbereich nicht zusätzlich für die Workload-Identitätsföderation 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 ein aktuelles SPIFFE-JWT-SVID gegen ein von OpenAI ausgestelltes Zugriffstoken eintauscht.
Die folgenden SDK-Beispiele setzen voraus, dass deine SPIFFE-Integration das JWT-SVID regelmäßig erneuert und in die Datei /var/run/spiffe/openai.jwt schreibt. Stelle sicher, dass nur der Workload die Datei lesen kann. Da JWT-SVIDs kurzlebig sind, musst du die Datei aktualisieren, bevor das Token abläuft. Alternativ kannst du das JWT-SVID nach Möglichkeit im Subject-Token-Provider über eine SPIFFE-Bibliothek für deine Programmiersprache direkt aus der SPIFFE Workload API abrufen. So vermeidest du veraltete Token-Dateien.
Setze OPENAI_IDENTITY_PROVIDER_ID und OPENAI_SERVICE_ACCOUNT_ID in der Umgebung des Workloads. Die Token-Datei enthält das externe Subject-Token. OPENAI_IDENTITY_PROVIDER_ID bezeichnet den Identitätsanbieter für Workloads bei OpenAI und OPENAI_SERVICE_ACCOUNT_ID das OpenAI-Zieldienstkonto. OpenAI ermittelt dann anhand der Token-Claims eine passende Zuordnung für diesen Anbieter und dieses Dienstkonto.
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);Empfehlungen für SPIFFE
- Verwende JWT-SVIDs für die Workload-Identitätsföderation mit OpenAI. X.509-SVIDs eignen sich für die gegenseitige Authentifizierung per TLS, der OpenAI-Endpunkt für den Token-Austausch akzeptiert sie jedoch nicht.
- Verwende für den Zugriff auf OpenAI eine einzige, eigens dafür vorgesehene Audience. Vermeide zu allgemein gefasste Werte wie eine ganze Vertrauensdomäne oder den Namen einer Umgebung.
- Gleiche SPIFFE-IDs nach Möglichkeit exakt ab. Verwende Zuordnungen mit Platzhaltern nur, wenn die betroffenen Workloads bewusst demselben Vertrauensbereich angehören.
- Halte die Gültigkeitsdauer von JWT-SVIDs kurz, um das Risiko von Replay-Angriffen mit Bearer-Tokens zu verringern. OpenAI-Zugriffstokens sind nie länger gültig als das externe Subject-Token, das für den Austausch verwendet wurde.
- Gehe beim Wechsel der Signaturschlüssel sorgfältig vor. Veröffentliche während der Umstellung sowohl die alten als auch die neuen öffentlichen Schlüssel über OIDC Discovery. Wenn du ein hochgeladenes öffentliches JWKS verwendest, aktualisiere es, bevor du JWT-SVIDs mit einem neuen
kidausstellst. - Synchronisiere die Uhren des SPIRE Servers und der Workloads. Bei größeren Zeitabweichungen können 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 eines Workloads abrufen kann, kann versuchen, es gegen ein OpenAI-Zugriffstoken einzutauschen.
- Grenze OpenAI-Dienstkonten entsprechend den Berechtigungen deiner Anwendungen und Umgebungen voneinander ab. Verwende für voneinander unabhängige SPIFFE-Workloads kein gemeinsames Dienstkonto mit weitreichenden Berechtigungen.
- Überwache fehlgeschlagene Token-Austauschvorgänge und achte auf Abweichungen bei Aussteller, Audience, Signaturschlüssel und Zuordnung.