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 mit X.509-Zertifikaten konfigurieren

Tausche eine durch ein Clientzertifikat bestätigte Identität gegen ein kurzlebiges OpenAI-Zugriffstoken ein.

Mit der X.509-Workload-Identitätsföderation kann ein Workload die Identität aus seinem TLS-Clientzertifikat gegen ein kurzlebiges OpenAI-Zugriffstoken eintauschen. Anschließend ruft der Workload die OpenAI-API mit dem Zugriffstoken und einem akzeptierten Clientzertifikat auf. Das Zugriffstoken ersetzt den API-Schlüssel. Das Clientzertifikat ist weiterhin erforderlich.

Die OpenAI-API unterstützt die X.509-Workload-Identitätsföderation. Codex unterstützt sie nicht. Verwende für Codex ein OIDC-Token oder ein SPIFFE JWT-SVID.

Einzelheiten zu Anfragen und Antworten beim Tokenaustausch findest du in der Referenz zum Tokenaustausch für Workload-Identitäten. Informationen zu Berechtigungen für Mutual TLS, Zertifikatsanforderungen, Aktivierung, mTLS-Hosts und Zertifikatsrotation findest du im Leitfaden zu Mutual TLS.

So funktioniert der Austausch

Der Austausch einer X.509-Workload-Identität erfolgt in fünf Schritten:

  1. Deine Organisation lädt in ihren bestehenden Einstellungen für Mutual TLS ein vertrauenswürdiges Stammzertifikat hoch und aktiviert es.
  2. Ein X.509-Identitätsanbieter für Workloads leitet aus dem verifizierten Clientzertifikat openai.*-Attribute ab. Dabei muss er genau einen nicht leeren Wert für openai.subject ermitteln.
  3. Eine Dienstkontozuordnung berechtigt die abgeleitete Identität dazu, ein bestimmtes OpenAI-Dienstkonto innerhalb eines Projekts zu verwenden.
  4. Der Workload legt sein Zertifikat am X.509-Tokenendpunkt auf mtls.auth.openai.com vor und fordert ein kurzlebiges Bearer-Token an. Das Zertifikat wird über die TLS-Verbindung übermittelt. Der Anfragetext enthält kein subject_token.
  5. Zur Autorisierung des API-Aufrufs sendet der Workload das Bearer-Token und ein Clientzertifikat an eine API-Route auf mtls.api.openai.com.

Bei der Autorisierung einer API-Anfrage prüft die API das Bearer-Token und das Zertifikat unabhängig voneinander. Ein Zertifikat allein berechtigt nicht zum Aufruf der OpenAI-API.

Voraussetzungen

Du benötigst:

  • Die Berechtigung, Zertifikate für Mutual TLS und Identitätsanbieter für Workloads in deiner Organisation zu verwalten.
  • Ein Projekt und ein Dienstkonto für den Workload.
  • Ein Clientzertifikat, den zugehörigen privaten Schlüssel und alle Zwischenzertifikate, die für eine Zertifikatskette bis zu deinem vertrauenswürdigen Stammzertifikat erforderlich sind.
  • Ein aktives, vertrauenswürdiges Stammzertifikat auf Organisations- oder Projektebene.

Bewahre private Schlüssel außerhalb der Versionsverwaltung auf. Gewähre nur dem Workload Zugriff, der sie verwendet. Schreibe keine privaten Schlüssel, Zertifikatsinhalte oder zurückgegebenen Zugriffstoken in Protokolle.

Vertrauenswürdige Zertifikate für Mutual TLS konfigurieren

X.509-Identitätsanbieter für Workloads verwenden die bestehende Zertifikatskonfiguration deiner Organisation für Mutual TLS. Sie laden selbst keine Zertifikate hoch und führen keinen eigenen Speicher für vertrauenswürdige Zertifikate.

Informiere dich im Leitfaden zu Mutual TLS über Zertifikatsanforderungen, mTLS-Hosts, die Auswirkungen der Zertifikatsaktivierung, CEL-Filter und die Clientkonfiguration. Öffne anschließend Organisationseinstellungen > Sicherheit > Mutual TLS. Lade das vertrauenswürdige Zertifikat im PEM-Format hoch und aktiviere es für die Organisation oder für jedes Projekt, das die X.509-Workload-Identitätsföderation verwenden soll.

Wenn die Zertifikatskette deines Clients über ein Zwischenzertifikat führt, konfiguriere den stabilen Vertrauensanker. Übermittle beim TLS-Handshake zuerst das Endzertifikat und danach die aktuellen Zwischenzertifikate. OpenAI verwendet die mit der Anfrage übermittelten Zwischenzertifikate und ruft fehlende Zwischenzertifikate nicht über Zertifikats-URLs ab.

Einen X.509-Anbieter konfigurieren

So konfigurierst du einen X.509-Anbieter:

  1. Öffne Organisationseinstellungen > Sicherheit > Identitätsanbieter für Workloads und wähle Identitätsanbieter erstellen.
  2. Wähle X.509 als Anbietertyp. Gib anschließend einen Namen und optional eine Beschreibung ein. X.509-Anbieter verwenden keine OIDC-Einstellungen für Aussteller, Zielgruppe, Discovery oder JWKS. Nach dem Erstellen kannst du den Anbietertyp nicht mehr ändern.
  3. Unter Erweitert kannst du für Attributbedingungen einen CEL-Ausdruck hinzufügen, um Zertifikate abzulehnen, bevor der Anbieter nach einer passenden Zuordnung sucht.
  4. Gib unter Attributtransformationen einen nicht leeren Ausdruck für die erforderliche Transformation openai.subject ein. Wenn du X.509 auswählst, fügt das Dashboard die Zeile subject hinzu. Es zeigt das Präfix openai. an und wendet es an. Wähle ein Zertifikatsmerkmal, das sich nicht ändert und den Workload identifiziert.
  5. Bei Bedarf kannst du weitere Transformationen mit jeweils eindeutigen openai.*-Namen hinzufügen. Wähle anschließend Erstellen.

Diese Beispielkonfiguration verwendet den Common Name des Zertifikats als kanonischen Subject-Wert und stellt die Organisationseinheit als zusätzliches Attribut für Zuordnungen bereit:

[
  {
    "attribute": "openai.subject",
    "expression": "assertion.subject.common_name"
  },
  {
    "attribute": "openai.environment",
    "expression": "assertion.subject.organizational_unit"
  }
]

Die Zertifikatsmerkmale stehen unter assertion.subject und assertion.subject_alt_names zur Verfügung. Transformationen, deren Ergebnisse du für Zuordnungen verwendest, müssen skalare Werte liefern. Jede zusätzliche Transformation benötigt einen eindeutigen openai.*-Namen.

Mit einem Ausdruck unter Attributbedingungen kannst du den Anbieter beispielsweise auf Zertifikate für den Produktivbetrieb beschränken:

assertion.subject.organizational_unit == "Production"

Eine Dienstkontozuordnung erstellen

  1. Wähle auf der Detailseite des X.509-Anbieters Zuordnung erstellen.
  2. Wähle das Zielprojekt und das Dienstkonto aus. Erteile nur die API-Berechtigungen, die der Workload benötigt.
  3. Lege in den Feldern Schlüssel und Wert fest, welchen Wert openai.subject exakt haben muss. X.509-Zuordnungen unterstützen entweder ein leeres Objekt ({}) ohne Assertions oder Assertions, deren Schlüssel mit openai. beginnen.
  4. Wähle Erstellen.

Beispiel:

Schlüssel Wert
openai.subject payments-service-prod

X.509-Zuordnungen verwenden die abgeleiteten openai.*-Attribute. Sie gleichen keine unverarbeiteten JWT-Claims wie sub, iss oder aud ab.

Die Anbieter-ID findest du in der Anbieterliste. In den Details der Zuordnung siehst du das ausgewählte Dienstkonto und seine Dienstkonto-ID. Notiere beide IDs. Der Workload sendet sie beim Tokenaustausch mit.

Eine X.509-Workload-Identität mit einem SDK verwenden

Lege Umgebungsvariablen für die Zertifikatskette, den privaten Schlüssel, den Anbieter und das Dienstkonto fest:

export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"
export OPENAI_IDENTITY_PROVIDER_ID="idp_example"
export OPENAI_SERVICE_ACCOUNT_ID="svc_acct_example"

Die Datei mit der Zertifikatskette sollte zuerst das Endzertifikat und danach alle benötigten Zwischenzertifikate enthalten. Übermittle im Anfragetext weder Zertifikatsdaten noch ein subject_token.

Konfiguriere einen Client des OpenAI-SDKs mit diesen Werten. Das SDK übermittelt das Clientzertifikat beim Tokenaustausch und bei API-Anfragen, sendet API-Anfragen an den mTLS-Endpunkt und erneuert kurzlebige Zugriffstoken automatisch.

Mit einem X.509-Clientzertifikat authentifizieren
import { readFile } from "node:fs/promises";

import OpenAI from "openai";
import { workloadIdentity } from "openai/auth/x509-transport";

const certificatePath = process.env.OPENAI_MTLS_CERT_CHAIN;
const privateKeyPath = process.env.OPENAI_MTLS_KEY;
const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;

if (
  !certificatePath ||
  !privateKeyPath ||
  !identityProviderId ||
  !serviceAccountId
) {
  throw new Error(
    "Set OPENAI_MTLS_CERT_CHAIN, OPENAI_MTLS_KEY, OPENAI_IDENTITY_PROVIDER_ID, and OPENAI_SERVICE_ACCOUNT_ID"
  );
}

const credential = workloadIdentity.fromX509({
  certificateChain: await readFile(certificatePath, "utf8"),
  privateKey: await readFile(privateKeyPath, "utf8"),
  identityProviderId,
  serviceAccountId,
});

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

  console.log(response.output_text);
} finally {
  await credential.close();
}

Diese Beispiele erfordern Versionen der OpenAI-SDKs, die die gezeigte X.509-Konfiguration unterstützen: TypeScript ab 7.8.0 mit installierter Peer-Abhängigkeit undici, Python ab 3.6.0, Go ab 3.54.0, Java ab 4.55.0 und Ruby ab 0.83.0.

Das Java-Beispiel lädt einen PKCS12-Schlüsselspeicher, um seinen X509ExtendedKeyManager zu erstellen. Für den X509TrustManager verwendet es den standardmäßigen Vertrauensspeicher der Plattform. Setze für dieses Beispiel OPENAI_X509_KEYSTORE_PATH, OPENAI_X509_KEYSTORE_PASSWORD und OPENAI_X509_CERTIFICATE_ALIAS. Alternativ kannst du dem SDK Manager übergeben, die PEM-Dateien oder Hardware verwenden.

Das Zertifikat manuell eintauschen

Wenn du das Protokoll für den Tokenaustausch direkt untersuchen oder selbst implementieren möchtest, übermittle das Zertifikat an den X.509-Tokenendpunkt:

curl --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --request POST "https://mtls.auth.openai.com/oauth/token" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token_type": "urn:openai:params:oauth:token-type:x509",
  "identity_provider_id": "${OPENAI_IDENTITY_PROVIDER_ID}",
  "service_account_id": "${OPENAI_SERVICE_ACCOUNT_ID}"
}
JSON

Bei erfolgreichem Austausch erhältst du ein gewöhnliches kurzlebiges Bearer-Token:

{
  "access_token": "eyJ...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": 1789045200,
  "scope": "api.model.read api.model.request"
}

Die Antwort enthält die Eigenschaft scope nur, wenn für die passende Dienstkontozuordnung Berechtigungen festgelegt sind.

Die Ablaufwerte dienen als Beispiel. Läuft das verifizierte Clientzertifikat früher ab, kann die zurückgegebene Gültigkeitsdauer kürzer sein. Die Referenz zu den Antwortfeldern beim Tokenaustausch erläutert die Einheiten und die Bedeutung von expires_in und expires_at.

Lies den Wert von access_token aus der erfolgreichen Antwort aus und speichere ihn im Anmeldedatenspeicher deiner Anwendung oder in einer Umgebungsvariablen wie OPENAI_WIF_ACCESS_TOKEN. Halte den Wert geheim. Gib ihn nicht aus, protokolliere ihn nicht und nimm ihn nicht in die Versionsverwaltung auf.

Die OpenAI-API manuell aufrufen

Setze OPENAI_MODEL auf gpt-6-astra, das aktuelle Standardmodell, oder auf ein anderes Modell, das dem Zielprojekt zur Verfügung steht. Sende anschließend das Bearer-Token und ein akzeptiertes Clientzertifikat an den mTLS-Endpunkt der API:

curl --request POST \
  --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --header "Authorization: Bearer $OPENAI_WIF_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data "{\"model\":\"$OPENAI_MODEL\",\"input\":\"Say hello in one sentence.\"}" \
  "https://mtls.api.openai.com/v1/responses"

Verwende das Bearer-Token anstelle eines API-Schlüssels und übermittle bei der API-Anfrage weiterhin ein akzeptiertes Clientzertifikat.

Das Bearer-Token ist kryptografisch nicht an das Zertifikat gebunden. Am einfachsten verwendest du für die API-Anfrage dasselbe Zertifikat wie beim Tokenaustausch. Du kannst für die Anfrage auch ein anderes Zertifikat verwenden, sofern es eigenständig dieselbe aktuell geltende mTLS-Richtlinie der API erfüllt.

Gültigkeitsdauer und Erneuerung von Token

Ein X.509-Workload-Identitätstoken ist höchstens eine Stunde gültig und läuft spätestens mit dem verifizierten Clientzertifikat ab. Beim Austausch erhältst du kein Refresh-Token. Tausche das Zertifikat erneut ein, um ein neues Zugriffstoken zu erhalten.

Speichere bei einem manuellen Austausch expires_at zusammen mit dem Zugriffstoken und plane den nächsten Austausch vor diesem Zeitpunkt ein. Berücksichtige Abweichungen zwischen den Systemuhren und die Latenz der Anfrage. Ein Beispiel findest du in den Hinweisen zur Tokenerneuerung.

Wenn du ein Zwischenzertifikat austauschst, musst du das konfigurierte Stammzertifikat nicht ändern. Übermittle bei jedem weiteren Tokenaustausch und bei allen weiteren API-Anfragen die neue vollständige Zertifikatskette.

Fehler beim Tokenaustausch beheben

Beim X.509-Tokenaustausch erhältst du im Fehlerfall allgemeine OAuth-Fehler. Sie enthalten keine Details zum Zertifikat, zum Stammzertifikat, zum Anbieter oder zur Zuordnung.

Ergebnis Typische Ursachen
HTTP 403 Methode oder Pfad der Anfrage weichen von der vorgeschriebenen Kombination POST /oauth/token auf mtls.auth.openai.com ab.
invalid_subject_token Das TLS-Clientzertifikat fehlt oder ist ungültig, die übermittelte Kette reicht nicht bis zu einem aktiven Stammzertifikat, der aktuelle Zeitpunkt liegt außerhalb des Gültigkeitszeitraums des Zertifikats oder eine Zulassungsregel für Mutual TLS lehnt das Zertifikat ab.
invalid_grant Der Anbieter oder die Zuordnung ist ungültig oder deaktiviert, ein Ausdruck unter Attributbedingungen des Anbieters lehnt die Identität ab, kein anwendbares Stammzertifikat ist aktiv oder keine Zuordnung passt.
Serverfehler OpenAI hat einen vorübergehenden Serverfehler zurückgegeben. Wiederhole die Anfrage so, wie du es für vorübergehende Fehler vorgesehen hast.

Beim X.509-Austausch erfolgt kein Rückgriff auf OIDC oder ein herkömmliches OAuth-Verfahren.

Einschränkungen

  • X.509-Identitätsanbieter für Workloads führen keinen eigenen Speicher für vertrauenswürdige Zertifikate.
  • Das Bearer-Token ist nicht an ein Zertifikat gebunden und verwendet weder DPoP noch einen cnf-Claim.
  • Durch den Zertifikatsaustausch lässt sich ein API-Aufruf nicht allein mit einem Zertifikat autorisieren. Für API-Anfragen sind weiterhin das Bearer-Token und ein akzeptiertes Clientzertifikat erforderlich.
  • OpenAI ruft fehlende Zwischenzertifikate nicht über AIA-URLs ab. Übermittle beim TLS-Handshake die vollständige Zertifikatskette.
  • OpenAI prüft bei diesem Verfahren den Sperrstatus von Zertifikaten weder anhand von Zertifikatssperrlisten (CRLs) noch per OCSP. Berücksichtige bei der Planung deiner Reaktion auf Zertifikatsvorfälle, wie du die Stammzertifikate für Mutual TLS, die Anbieter und die Zuordnungen steuern kannst und wie kurz die ausgestellten Token gültig sind.
  • Dieses Verfahren bietet keine Unterstützung für SPIFFE X.509-SVIDs. Der SPIFFE-Leitfaden verwendet weiterhin JWT-SVIDs.