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-Identitätsföderation für Kubernetes konfigurieren

Nutze Kubernetes als Identitätsanbieter für Workloads, indem du ein projiziertes Token eines Kubernetes-Dienstkontos gegen ein kurzlebiges OpenAI-Zugriffstoken eintauschst.

Kubernetes einrichten

Diese Anleitung setzt voraus, dass die Tokenprojektion für Kubernetes-Dienstkonten aktiviert ist. In aktuellen Kubernetes-Versionen ist sie standardmäßig verfügbar. Die Workload-Identitätsföderation von OpenAI erfordert OIDC-kompatible projizierte Dienstkonto-Token. Ältere Kubernetes-Dienstkonto-Token, die in Secrets gespeichert sind, unterstützt OpenAI nicht.

Verwende für die Workload, die auf die OpenAI-API zugreifen muss, ein Kubernetes-Dienstkonto vom Typ ServiceAccount. Falls du noch keines hast, erstelle es mit folgendem Befehl:

kubectl create serviceaccount openai-wif --namespace default

Rufe den OIDC-Issuer deines Kubernetes-Clusters ab:

kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

Auch wenn du das JWKS hochlädst und OpenAI keine JWKS-Discovery beim OIDC-Issuer durchführt, muss dieser Issuer mit dem Issuer übereinstimmen, den du beim Identitätsanbieter für Workloads konfiguriert hast.

Rufe das JWKS des Clusters ab und speichere den zurückgegebenen Schlüsselsatz. Du brauchst ihn, wenn du den Identitätsanbieter für Workloads konfigurierst:

kubectl get --raw /openid/v1/jwks

Konfiguriere das projizierte Dienstkonto-Token mit der von OpenAI erwarteten Audience und einer für deine Workload geeigneten Gültigkeitsdauer. OpenAI prüft Issuer, Signatur, Audience und Ablaufzeit des Tokens. In diesem Beispiel ist die Token-Datei unter /var/run/secrets/tokens/token eingebunden. Das Token hat die Audience https://api.openai.com/v1 und läuft nach 3600 Sekunden ab. Du kannst eine andere Audience verwenden, solange die Audience im projizierten Token mit der Audience übereinstimmt, die du in OpenAI beim Identitätsanbieter für Workloads konfiguriert hast:

apiVersion: v1
kind: Pod
metadata:
  name: openai-wif-app
  namespace: default
spec:
  serviceAccountName: openai-wif
  containers:
    - name: app
      image: my-image
      volumeMounts:
        - name: ksa-token
          mountPath: /var/run/secrets/tokens
          readOnly: true
  volumes:
    - name: ksa-token
      projected:
        sources:
          - serviceAccountToken:
              path: token
              audience: "https://api.openai.com/v1"
              expirationSeconds: 3600

Token prüfen

Bevor du die Workload-Identitätsföderation konfigurierst, dekodiere ein projiziertes Dienstkonto-Token lokal und prüfe seine Claims. Rufe das Token aus einem laufenden Pod ab, in dem es eingebunden ist, und exportiere es als TOKEN:

TOKEN=$(kubectl exec -n default openai-wif-app -- cat /var/run/secrets/tokens/token)
export TOKEN

Führe anschließend dieses Skript aus:

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. Verwende für Token aus dem Produktivbetrieb einen lokalen Decoder und füge diese Token nicht in Tools von Drittanbietern ein.

Ein dekodiertes projiziertes Token eines Kubernetes-Dienstkontos sieht etwa so aus:

{
  "iss": "https://kubernetes.example.com",
  "aud": ["https://api.openai.com/v1"],
  "sub": "system:serviceaccount:default:openai-wif",
  "iat": 1716235422,
  "exp": 1716239022,
  "kubernetes.io": {
    "namespace": "default",
    "serviceaccount": {
      "name": "openai-wif",
      "uid": "11111111-2222-3333-4444-555555555555"
    }
  }
}

Vergleiche die Werte in der dekodierten Payload des empfangenen Tokens mit dem Issuer, der Audience und den Zuordnungswerten, die du in OpenAI konfiguriert hast. Die meisten Konfigurationsfehler erkennst du schon vor dem Tokenaustausch an den Claims iss, aud und sub.

Workload-Identitätsföderation einrichten

Erstelle in OpenAI einen Identitätsanbieter für Workloads mit dem Issuer deines Kubernetes-Clusters. Füge anschließend eine Dienstkontozuordnung hinzu, die zu den Attributen des projizierten Tokens passt.

Konfiguriere zuerst den Identitätsanbieter für Workloads und erstelle dann die Dienstkontozuordnung.

Identitätsanbieter für Workloads einrichten

  1. Erstelle den Identitätsanbieter für Workloads. Gib unter Name einen eindeutigen Wert ein, etwa kubernetes-prod. Gib unter Beschreibung beispielsweise Production Kubernetes cluster ein, damit das Administrationsteam den Cluster identifizieren kann.

  2. Lege Issuer und Audience fest. Gib unter OIDC-Issuer-URL den Issuer ein, den kubectl get --raw /.well-known/openid-configuration | jq -r .issuer zurückgibt. Dieser Wert muss mit dem Claim iss im projizierten Token übereinstimmen. Gib unter Audience exakt die Zeichenfolge ein, die du im Volume für das projizierte Dienstkonto-Token als Audience konfiguriert hast. Sie wird als opaker Wert behandelt. In diesem Beispiel lautet der Wert https://api.openai.com/v1.

  3. Lade das Kubernetes-JWKS hoch. Aktiviere Hochgeladenes JWKS zur Tokenprüfung verwenden und füge unter JWKS-JSON die Ausgabe von kubectl get --raw /openid/v1/jwks ein. Mit diesem Satz öffentlicher Schlüssel prüft OpenAI die projizierten Token von Kubernetes-Dienstkonten. Lade den vollständigen Schlüsselsatz einschließlich des Felds keys hoch.

    Hinweis: Für selbst gehostete Kubernetes-Cluster unterstützt OpenAI nur den lokalen JWKS-Modus. Lade das JWKS hoch, das dein Cluster zurückgibt. OpenAI führt beim konfigurierten Issuer keine OIDC-Discovery durch. OpenAI vergleicht den konfigurierten Issuer weiterhin mit dem Feld iss im Token.

    Wenn dein Cluster die Signaturschlüssel für Dienstkonten wechselt, aktualisiere das hochgeladene JWKS in der Konfiguration des Identitätsanbieters. OpenAI lehnt Token ab, deren Signaturschlüssel im konfigurierten JWKS fehlt. Enthält das JWKS mehrere aktive öffentliche Schlüssel, lade das vollständige Array keys hoch.

  4. Füge Attributtransformationen nur hinzu, wenn du für die Zuordnung abgeleitete Attribute brauchst. Unveränderte Token-Claims wie sub, aud und iss kannst du direkt in den Zuordnungsbedingungen verwenden. Wenn du transformierte Attribute für den Abgleich verwendest, fügt das Dashboard automatisch das Präfix openai. hinzu. Gib beispielsweise workload_subject mit dem Ausdruck assertion.sub ein, um openai.workload_subject zu erstellen. Unveränderte Token-Claims, die bereits mit openai. beginnen, werden für Zuordnungsschlüssel mit dem Präfix openai. nur berücksichtigt, wenn du eine passende Transformation konfiguriert hast.

Dienstkontozuordnung einrichten

  1. Erstelle eine Dienstkontozuordnung. Gib unter Name einen Wert ein, der innerhalb des Identitätsanbieters für Workloads eindeutig ist, etwa openai-mapping-kubernetes. Gib unter Beschreibung beispielsweise Workload Identity Provider Mapping for Kubernetes Workloads ein, um anzugeben, welche Workload die Zuordnung verwenden kann.

  2. Gleiche das Subject des Kubernetes-Dienstkontos ab. Gib unter Schlüssel den Wert sub und unter Wert die Zeichenfolge system:serviceaccount:default:openai-wif ein. Für Kubernetes-Dienstkonten hat das Subject das Format system:serviceaccount:<namespace>:<service-account-name>.

  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 die Kubernetes-Workload verwenden darf, etwa kubernetes-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 zu verwenden.

  4. Schränke die API-Berechtigungen bei Bedarf ein. Wähle geeignete Berechtigungen wie api.model.request und api.vector_store.read aus, um die Zugriffsrechte der über diese Zuordnung ausgestellten Token weiter einzuschränken. Lass das Berechtigungsfeld leer, wenn du den Geltungsbereich nicht zusätzlich für die Workload-Identitätsföderation einschränken möchtest. Für den Zugriff mit dem Token gelten weiterhin die Berechtigungen des zugeordneten Dienstkontos.

Token im Code verwenden

Konfiguriere deinen OpenAI-SDK-Client so, dass er das projizierte Kubernetes-Token liest und gegen ein von OpenAI ausgestelltes Zugriffstoken eintauscht.

Gib im SDK beim Anbieter für die Workload-Identitätsföderation den Pfad zur eingebundenen Token-Datei, etwa /var/run/secrets/tokens/token, als Quelle für das Subject-Token an. Das SDK tauscht das Kubernetes-Token gegen ein von OpenAI ausgestelltes Zugriffstoken ein und authentifiziert damit API-Anfragen.

Die folgenden Beispiele initialisieren einen OpenAI-Client mit einem benutzerdefinierten Anbieter für Subject-Token. Der Anbieter liest das projizierte Token des Kubernetes-Dienstkontos aus der eingebundenen Datei und verwendet es als Subject-Token für die Workload-Identitätsföderation.

Mit einem projizierten Token eines Kubernetes-Dienstkontos authentifizieren
import { readFile } from "node:fs/promises";
import OpenAI from "openai";

const tokenPath = "/var/run/secrets/tokens/token";
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 mountedServiceAccountTokenProvider(path: string) {
  return {
    tokenType: "jwt" as const,
    getToken: async () => {
      const token = (await readFile(path, "utf8")).trim();
      if (!token) {
        throw new Error("The mounted service account token file is empty.");
      }
      return token;
    },
  };
}

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId,
    serviceAccountId,
    provider: mountedServiceAccountTokenProvider(tokenPath),
  },
});

const response = await client.responses.create({
  model: "gpt-5.6-terra",
  input: "Say hello from Kubernetes workload identity federation.",
});

console.log(response.output_text);

Empfehlungen für Kubernetes

  • Verwende einen stabilen OIDC-Issuer. Die Issuer-URL muss mit dem Claim iss im projizierten Dienstkonto-Token übereinstimmen und sollte auch bei Cluster-Upgrades und Wartungsarbeiten gleich bleiben.
  • Schütze die Signaturschlüssel sorgfältig. Wer Zugriff auf die Signaturschlüssel für Dienstkonten des Clusters hat, kann Token ausstellen, die OpenAI unter Umständen akzeptiert.
  • Verwende eigene Dienstkonten für OpenAI-Integrationen. Vermeide Dienstkonten, die auch für den Zugriff auf andere Infrastruktur oder Anwendungen genutzt werden.
  • Halte das hochgeladene JWKS aktuell. OpenAI prüft die Identitätstoken der Workloads im lokalen JWKS-Modus anhand des konfigurierten JWKS. Aktualisiere deshalb die Konfiguration des Identitätsanbieters, bevor du auf neue Signaturschlüssel umstellst.
  • Halte benutzerdefinierte Claims möglichst einfach. Verwende für den Abgleich vorzugsweise Standard-Claims wie sub und aud oder transformierte Attribute, die du direkt aus diesen Claims ableitest.
  • Berücksichtige in deinem Sicherheitsmodell, wer die Namespaces verwaltet. Wenn Personen mit administrativen Rechten für einen Namespace Dienstkonten erstellen können, grenze den Geltungsbereich der Zuordnungen so ein, dass niemand unbeabsichtigt zusätzliche Rechte erhält.
  • Überwache Änderungen am Issuer und an den Signaturschlüsseln. Wenn du die Signaturschlüssel wechselst, ohne das JWKS beim Identitätsanbieter für Workloads zu aktualisieren, kann der Tokenaustausch fehlschlagen.