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

Workloadidentitätsverbund für Microsoft Azure konfigurieren

Du kannst Microsoft Azure in zwei Szenarien als Identitätsanbieter für Workloads verwenden:

  • Verwaltete Azure-Identität: Tausche ein Zugriffstoken, das Microsoft Entra ID für eine verwaltete Identität ausgestellt hat, gegen ein kurzlebiges OpenAI-Zugriffstoken ein.
  • AKS: Tausche ein projiziertes Dienstkontotoken von Azure Kubernetes Service (AKS) gegen ein kurzlebiges OpenAI-Zugriffstoken ein.

Verwaltete Azure-Identität

Mit verwalteten Azure-Identitäten können Workloads, die in Azure ausgeführt werden, Token von Microsoft Entra anfordern, ohne langlebige Geheimnisse zu speichern. Beim Workloadidentitätsverbund mit OpenAI dient das Token der verwalteten Identität als Subjekttoken. OpenAI prüft dieses Token, bevor es ein OpenAI-Zugriffstoken ausstellt.

Verwaltete Azure-Identität einrichten

Erstelle oder verwende in Microsoft Entra eine App-Registrierung für die Tokenzielgruppe, der OpenAI vertrauen soll. Konfiguriere den Anwendungs-ID-URI. Deine Workload gibt diesen URI als Wert für resource an, wenn sie beim Azure Instance Metadata Service (IMDS) ein Token anfordert. Im ausgestellten Token erscheint der URI als Wert des Claims aud. Die Schritte für Microsoft Entra findest du in der Anleitung Eine neue Anwendung und einen Dienstprinzipal in Microsoft Entra ID erstellen.

Der in Microsoft Entra ID konfigurierte Anwendungs-ID-URI, der IMDS-Parameter resource, der Claim aud im ausgestellten Token und die Zielgruppe des Identitätsanbieters für Workloads in OpenAI müssen alle denselben Wert haben.

Erstelle eine verwaltete Identität und weise sie der Azure-Ressource zu, auf der deine Anwendung läuft, etwa einer virtuellen Maschine. Die Ressource muss IMDS zur Laufzeit aufrufen können. Weitere Informationen zur Konfiguration in Azure findest du in der Übersicht zu verwalteten Identitäten von Microsoft. Wie du die Identität zuweist, erfährst du in der Dokumentation zur jeweiligen Azure-Ressource.

Token für eine verwaltete Azure-Identität abrufen

Fordere auf der Azure-Ressource, der du die verwaltete Identität zugewiesen hast, ein Token von IMDS an. Gib den Anwendungs-ID-URI als Wert für den Parameter resource an. Dieses Token dient als Subjekttoken, das OpenAI gegen ein von OpenAI ausgestelltes Zugriffstoken eintauscht.

APPLICATION_ID_URI="api://<application-client-id>"

TOKEN=$(curl -sS -G -H "Metadata: true" \
  "http://169.254.169.254/metadata/identity/oauth2/token" \
  --data-urlencode "api-version=2018-02-01" \
  --data-urlencode "resource=${APPLICATION_ID_URI}" \
  | jq -r .access_token)
export TOKEN

Wenn der Ressource mehrere benutzerseitig zugewiesene verwaltete Identitäten zugeordnet sind, gib die gewünschte Identität über einen der Abfrageparameter client_id, object_id oder msi_res_id an. Microsoft beschreibt die Parameter für IMDS-Tokenanforderungen in der Anleitung Mit verwalteten Identitäten auf einer virtuellen Maschine ein Zugriffstoken abrufen.

Token prüfen

Bevor du den Workloadidentitätsverbund konfigurierst, exportiere das Token von Microsoft Entra als TOKEN. Führe anschließend dieses Skript lokal aus, um 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");
}
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 vermeide es, solche Token in Tools von Drittanbietern einzufügen.

Ein dekodiertes Token von Microsoft Entra ID für eine verwaltete Identität sieht etwa so aus:

{
  "iss": "https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/v2.0",
  "aud": "api://00000000-1111-2222-3333-444444444444",
  "tid": "11111111-2222-3333-4444-555555555555",
  "appid": "22222222-3333-4444-5555-666666666666",
  "oid": "33333333-4444-5555-6666-777777777777",
  "sub": "33333333-4444-5555-6666-777777777777",
  "xms_mirid": "/subscriptions/<subscription-id>/resourcegroups/my-resource-group/providers/Microsoft.Compute/virtualMachines/openai-wif-vm",
  "iat": 1716235422,
  "exp": 1716239022
}

Prüfe die Claims, die du in OpenAI konfigurieren möchtest:

  • iss: Übernimm den Ausstellerwert exakt aus dem Token. Der Wert kann https://login.microsoftonline.com/<tenant-id>/v2.0 lauten. Setze die Endung aber nicht voraus.
  • aud: Der Wert muss mit dem Anwendungs-ID-URI, dem IMDS-Parameter resource und der Zielgruppe des Identitätsanbieters für Workloads in OpenAI übereinstimmen.
  • tid: Die Mandanten-ID von Microsoft Entra.
  • appid: Die Anwendungs-ID (Client-ID) der verwalteten Identität, sofern der Claim vorhanden ist.
  • iat und exp: Prüfe die gesamte Gültigkeitsdauer des Tokens in Sekunden. Sie ergibt sich aus exp - iat.

Setze für Codex den Parameter max_assertion_lifetime_seconds des Anbieters auf einen genehmigten Grenzwert, der die erwartete Spanne der Tokenlaufzeiten dieses Ausstellers abdeckt. Verwende dafür nicht die Restlaufzeit des Tokens und gehe nicht davon aus, dass jedes Entra-Token eine Stunde lang gültig ist. Microsoft dokumentiert die variablen Laufzeiten von Zugriffstoken und unterstützt keine Konfiguration der Tokenlaufzeiten für verwaltete Identitäten.

Token für verwaltete Identitäten können auch Claims wie azp, oid, sub oder xms_mirid enthalten. Maßgeblich ist das dekodierte Token. Wähle Claims, die genau die verwaltete Identität und den Ressourcenbereich kennzeichnen, denen du vertraust.

Vergleiche anhand der dekodierten Payload die Werte im empfangenen Token mit dem Aussteller, der Zielgruppe und den Zuordnungswerten, die du in OpenAI konfiguriert hast. Die meisten Konfigurationsfehler erkennst du schon vor dem Tokenaustausch an den Claims iss, aud, tid und den Claims zur verwalteten Identität.

Workloadidentitätsverbund einrichten

Erstelle in OpenAI einen Identitätsanbieter für Workloads mit Microsoft Entra ID als Aussteller. Füge anschließend eine Dienstkontozuordnung hinzu, die stabile Claims aus dem Token der verwalteten Identität abgleicht.

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 azure-managed-identity-prod. Gib unter Beschreibung zum Beispiel Production Azure managed identity workloads ein, damit das Administrationsteam den Anbieter leicht erkennen kann.

  2. Lege Aussteller und Zielgruppe fest. Gib unter OIDC-Aussteller-URL exakt den Wert des Claims iss aus dem Token ein. Rufe dazu zunächst ein Beispieltoken für die verwaltete Identität ab und prüfe seine Claims. Die URL des Ausstellers kann zum Beispiel https://login.microsoftonline.com/<tenant-id>/v2.0 lauten. Gib unter Zielgruppe den Anwendungs-ID-URI ein, den du in Microsoft Entra konfiguriert hast, etwa api://<application-client-id>. Dieser Wert muss mit dem Claim aud im Token übereinstimmen.

  3. Verwende die Tokenprüfung über Microsoft Entra. Lass Hochgeladene JWKS zur Tokenprüfung verwenden deaktiviert. OpenAI prüft das Token der verwalteten Identität anhand der Ausstellermetadaten und JWKS von Microsoft Entra.

  4. Füge Attributtransformationen hinzu, wenn du abgeleitete Attribute für die Zuordnung benötigst. Gib zum Beispiel managed_identity_client_id mit dem Ausdruck assertion.appid ein, um openai.managed_identity_client_id aus dem Claim für die Anwendungs-ID (Client-ID) der verwalteten Identität zu erzeugen. Das Dashboard ergänzt das Präfix openai. automatisch. Ursprüngliche Token-Claims, deren Name bereits mit openai. beginnt, werden für Zuordnungsschlüssel mit dem Präfix openai. nur berücksichtigt, wenn du eine passende Transformation konfigurierst.

Dienstkontozuordnung einrichten

  1. Erstelle eine Dienstkontozuordnung. Gib unter Name einen Wert ein, der innerhalb dieses Identitätsanbieters für Workloads eindeutig ist, etwa vm-openai-wif. Gib unter Beschreibung zum Beispiel Production VM Azure managed identity workload ein, um festzuhalten, welche Workload die Zuordnung verwenden kann.

  2. Gleiche stabile Claims der verwalteten Identität ab. Füge für jeden Claim, der übereinstimmen muss, eine Zeile mit Schlüssel und Wert hinzu. Enthält das Token den Claim appid, gib unter Schlüssel appid und unter Wert die Client-ID der verwalteten Identität ein. Der Claim appid enthält die Anwendungs-ID (Client-ID) der verwalteten Identität. Er ist in der Regel der stabilste Claim, um eine Zuordnung an eine bestimmte verwaltete Identität zu binden. Enthält dein Token keinen Claim appid, verwende einen anderen stabilen Claim aus dem dekodierten Token, etwa azp, oid, sub oder xms_mirid. Um die Zuordnung auf einen Mandanten zu beschränken, gib in einer weiteren Zeile unter Schlüssel tid und unter Wert die Mandanten-ID von Microsoft Entra ein. Dekodiere ein Beispieltoken von IMDS und verwende Claims, die für die verwaltete Identität und die Ressource, denen du vertraust, stabil bleiben.

  3. Wähle das Ziel in OpenAI. Wähle unter Projekt das OpenAI-Projekt aus, zu dem das Zieldienstkonto gehört. Wähle unter Dienstkonto das OpenAI-Dienstkonto aus, das die Azure-Workload verwenden darf, etwa azure-managed-identity-prod-openai-wif.

  4. Schränke bei Bedarf die API-Berechtigungen ein. Wähle passende Berechtigungen wie api.model.request und api.vector_store.read aus, um den Zugriff mit Token aus dieser Zuordnung weiter einzugrenzen. Lass das Berechtigungsfeld leer, wenn du den Geltungsbereich nicht zusätzlich für den Workloadidentitätsverbund 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 bei IMDS ein Token für die verwaltete Azure-Identität anfordert und es gegen ein von OpenAI ausgestelltes Zugriffstoken eintauscht.

Setze OPENAI_WIF_AUDIENCE auf den Anwendungs-ID-URI von Microsoft Entra, den du als Zielgruppe des Identitätsanbieters für Workloads konfiguriert hast. Das SDK fordert für diese Zielgruppe ein Token für die verwaltete Identität an, tauscht es gegen ein von OpenAI ausgestelltes Zugriffstoken ein und authentifiziert API-Anfragen mit dem OpenAI-Token.

Mit einem Token für eine verwaltete Azure-Identität authentifizieren
import OpenAI from "openai";

const imdsEndpoint = "http://169.254.169.254/metadata/identity/oauth2/token";

const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;
const audience = process.env.OPENAI_WIF_AUDIENCE;

if (!identityProviderId || !serviceAccountId || !audience) {
  throw new Error(
    "Set OPENAI_IDENTITY_PROVIDER_ID, OPENAI_SERVICE_ACCOUNT_ID, and OPENAI_WIF_AUDIENCE"
  );
}

function azureManagedIdentityTokenProvider(resource: string) {
  return {
    tokenType: "jwt" as const,
    getToken: async () => {
      const url = new URL(imdsEndpoint);
      url.searchParams.set("api-version", "2018-02-01");
      url.searchParams.set("resource", resource);

      const clientId = process.env.AZURE_CLIENT_ID;
      if (clientId) {
        url.searchParams.set("client_id", clientId);
      }

      const response = await fetch(url, {
        headers: { Metadata: "true" },
      });

      if (!response.ok) {
        throw new Error(
          `Azure IMDS token request failed with status ${response.status}.`
        );
      }

      const body = await response.json();
      if (!body.access_token) {
        throw new Error("Azure IMDS did not return an access token.");
      }

      return body.access_token;
    },
  };
}

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

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

console.log(response.output_text);

Empfehlungen für Microsoft Azure

  • Verwende nach Möglichkeit verwaltete Identitäten. Sie ermöglichen eine einfachere und sicherere Authentifizierung als die manuelle Verteilung von Anmeldeinformationen.
  • Verwende für unterschiedliche Anwendungen und Umgebungen jeweils eigene verwaltete Identitäten, Microsoft-Entra-Anwendungen und OpenAI-Zuordnungen. Vermeide es, dieselbe Identität für Workloads in Entwicklung, Staging und Produktion zu verwenden.
  • Beschränke die zulässigen Zielgruppen. Konfiguriere nur die Zielgruppen, die du für den Workloadidentitätsverbund mit OpenAI benötigst.
  • Verwende für jeden Sicherheitsbereich eine eigene Anwendung in Microsoft Entra ID. So lassen sich Zuständigkeiten klarer zuordnen, Zugriffe besser prüfen und Berechtigungen leichter verwalten.
  • Verwende vorzugsweise eigene Zuordnungen für einzelne Workloads. Gleiche Claims ab, die die jeweilige Workload kennzeichnen, anstelle allgemeiner Attribute, die für den gesamten Mandanten gelten.
  • Prüfe regelmäßig die Konfiguration deiner Verbundanmeldeinformationen. Veraltete Anmeldeinformationen können unbeabsichtigt weiterhin Zugriff gewähren, lange nachdem du die zugehörigen Workloads außer Betrieb genommen hast.
  • Trenne Identitäten für den Produktivbetrieb von denen für andere Umgebungen. Produktive Workloads sollten sich über eigene Verbundidentitäten und OpenAI-Dienstkonten authentifizieren.