So konfigurieren Sie Azure OpenAI in Microsoft Foundry Models mit Microsoft Entra ID Authentifizierung (klassisch)

Gilt nur für:klassisches Foundry-Portal. Dieser Artikel ist für das neue Foundry-Portal nicht verfügbar. Erfahren Sie mehr über das neue Portal.

Hinweis

Links in diesem Artikel können Inhalte in der neuen Microsoft Foundry-Dokumentation anstelle der jetzt angezeigten Foundry-Dokumentation (klassisch) öffnen.

mit Microsoft Entra ID können Sie Ihre Azure OpenAI-Ressource aufrufen, ohne einen API-Schlüssel in Ihrer Anwendung zu speichern. Statt eines Schlüssels fordert Ihr Code ein kurzlebiges Zugriffstoken für eine Identität an, die Sie einer Rolle für die Ressource gewähren. In diesem Artikel wird erläutert, wie Sie zwei Methoden authentifizieren: als sich selbst während der lokalen Entwicklung und als verwaltete Identität, wenn Ihre App in Azure ausgeführt wird.

Entra ID Authentifizierung im Vergleich zu verwalteten Identitäten

Diese beiden Begriffe werden häufig austauschbar verwendet, aber sie beschreiben unterschiedliche Dinge.

Microsoft Entra ID ist die Identitätsplattform. Jeder tokenbasierte Aufruf von Azure OpenAI durchläuft ihn, unabhängig davon, welche Identität Sie verwenden.

Eine verwaltete Identität ist eine Art von Entra-Identität. Azure erstellt sie, weist sie einer Azure Ressource wie einem virtuellen Computer oder einer Web-App zu und dreht ihre Anmeldeinformationen für Sie. Es gibt kein Geheimnis für Sie, um sie zu speichern oder zu drehen.

Die Identität, mit der Sie sich authentifizieren, hängt davon ab, wo Ihr Code ausgeführt wird:

Identity	Wo es benutzt wird	Geheimer Schlüssel zum Verwalten
Ihr Entwicklerkonto	Ihr lokaler Computer, nachdem Sie ausgeführt haben `az login`	None. Die Azure CLI hält die Sitzung.
Vom System zugewiesene verwaltete Identität	Eine Azure Ressource, die an den Lebenszyklus dieser Ressource gebunden ist	None. Azure verwaltet sie.
Vom Benutzer zugewiesene verwaltete Identität	Mehrere Azure Ressourcen, die eine Identität gemeinsam nutzen	None. Azure verwaltet sie.
Service Principal	CI/CD-Pipelines und Nicht-Azure Hosts	Ein geheimer Clientschlüssel oder ein Zertifikat, das Sie drehen

Verwenden Sie eine vom System zugewiesene verwaltete Identität, wenn eine einzelne Ressource Zugriff benötigt. Verwenden Sie eine vom Benutzer zugewiesene verwaltete Identität, wenn mehrere Ressourcen denselben Zugriff benötigen oder wenn Sie die Rolle gewähren möchten, bevor Sie die Ressource erstellen, die sie verwendet.

Sie müssen für jeden dieser Code keinen anderen Code schreiben. Die DefaultAzureCredential Klasse in der Azure Identitätsbibliothek versucht eine Kette von Anmeldeinformationen in der Reihenfolge und verwendet die erste, die sie findet. Auf Ihrem Laptop nimmt sie Ihre az login Sitzung auf. Auf einem Azure-Host übernimmt er die verwaltete Identität. Aus diesem Grund funktioniert das gleiche Beispiel an beiden Stellen, und deshalb behandelt dieser Artikel beide.

Voraussetzungen

Ein Azure-Abonnement – Create one for free
Eine Azure OpenAI-Ressource mit einem benutzerdefinierten Subdomänennamen. Sie benötigen eine benutzerdefinierte Unterdomäne für Microsoft Entra ID Authentifizierung.
Ein Modell, das für Ihre Ressource bereitgestellt wird.
Azure CLI - Installationshandbuch
Python 3.8 oder höher, wobei die folgenden Pakete installiert sind:
```
pip install openai azure-identity
```

Zuweisen einer Rolle

Rollenzuweisungen steuern, wer Ihre Ressource aufrufen kann. Weisen Sie sich entweder die Rolle "Cognitive Services OpenAI User" oder "Cognitive Services OpenAI Contributor" für die Azure OpenAI-Ressource zu. Mit beiden Rollen können Sie API-Aufrufe mit Ihrer eigenen Identität anstelle eines Schlüssels ableiten.

Weisen Sie die gleiche Rolle später der verwalteten Identität Ihrer App zu, wenn Sie sie für Azure bereitstellen.

Important

Rollenzuweisungen können bis zu fünf Minuten in Kraft treten. Wenn Sie direkt nach dem Zuweisen einer Rolle einen 403 Fehler erhalten, warten Sie, und versuchen Sie es erneut, bevor Sie etwas anderes beheben.

Authentifizieren von Ihrem Entwicklungscomputer

Verwendet auf Ihrem lokalen Computer DefaultAzureCredential Ihre Azure CLI Sitzung. Melden Sie sich zuerst an. Möglicherweise müssen Sie sich erneut anmelden, wenn Ihre Sitzung zu lang im Leerlauf ist.

az login

Wenn Sie zu mehreren Mandanten gehören, melden Sie sich beim Mandanten an, der Ihre Azure OpenAI-Ressource enthält:

az login --tenant YOUR-TENANT-ID

Rufen Sie jetzt Ihr Modell auf. In diesem Beispiel wird ein Token angefordert und dann eine Chatabschlussanforderung gesendet.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

response = client.chat.completions.create(
    model="gpt-4o",  # Use your deployment name, which might differ from the model name.
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},
        {"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."},
        {"role": "user", "content": "Do other Azure services support this too?"}
    ]
)

print(response.choices[0].message.content)

Warum das Beispiel ein Token an `api_key`

Der api_key Parameter sieht in einem schlüssellosen Beispiel aus, und es ist der häufigste Punkt der Verwirrung in diesem Workflow. Hier erfahren Sie, was passiert.

Der api_key Parameter akzeptiert entweder eine Zeichenfolge oder eine aufrufbare Zeichenfolge. Wenn Sie den token_provider aufrufbaren Wert übergeben, ruft der Client es vor jeder Anforderung auf, ein aktuelles Microsoft Entra Zugriffstoken abzurufen, und sendet dieses Token dann als Bearertoken im Authorization Header. Es wird kein API-Schlüssel erstellt, gespeichert oder übertragen. Der Parameter behält den Namen api_key zur Kompatibilität mit der OpenAI-Clientbibliothek bei, der einen Parameter für beide Authentifizierungsstile verwendet.

Die get_bearer_token_provider Funktion verarbeitet das Zwischenspeichern und Aktualisieren von Token für Sie, sodass Sie den Ablauf des Tokens nicht selbst nachverfolgen müssen.

Überprüfen Des Zugriffs

Um zu bestätigen, dass die Rollenzuweisung funktioniert, bevor Sie Code ausführen, fordern Sie ein Token an, und rufen Sie die API direkt auf. Diese Methode bietet auch die klarste Möglichkeit, den Authorization Header anzuzeigen, den die Clientbibliothek für Sie festlegt.

TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken --output tsv)

curl https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Authentifizieren von einer Azure gehosteten App mithilfe einer verwalteten Identität

Wenn Ihr Code auf einem Azure virtuellen Computer, web app, Funktions-App, Container-App oder vm-Skalierungssatz ausgeführt wird, verwenden Sie eine verwaltete Identität anstelle Ihres Entwicklerkontos. Ihre App speichert niemals anmeldeinformationen, und Azure die Identität für Sie dreht.

Aktivieren und Zuweisen der Identität

Aktivieren Sie eine verwaltete Identität in der Azure Ressource, die Ihre App hosten soll. Eine virtuelle Maschine finden Sie in der Schnellstartanleitung für Ihr bevorzugtes Tool: Azure Portal, Azure PowerShell, Azure CLI, Azure Resource Manager Vorlage oder Azure Resource Manager Clientbibliotheken.
Weisen Sie der verwalteten Identität die Rolle "Cognitive Services OpenAI User" in Ihrer Azure OpenAI-Ressource zu, auf die gleiche Weise wie für Ihr eigenes Konto in "Zuweisen einer Rolle".

Verwenden einer systemseitig zugewiesenen verwalteten Identität

Wenn der Host nur über eine vom System zugewiesene verwaltete Identität verfügt, funktioniert das Beispiel von Authenticate von Ihrem Entwicklungscomputer ohne Änderungen. DefaultAzureCredentialfindet die verwaltete Identität automatisch, wenn sie in Azure ausgeführt wird.

Verwenden einer benutzerseitig zugewiesenen verwalteten Identität

Ein Host kann ihm mehrere Identitäten zugewiesen haben, sodass Sie sagen müssen, welcher verwendet werden soll. Übergeben Sie die Client-ID der vom Benutzer zugewiesenen verwalteten Identität:

from openai import OpenAI
from azure.identity import ManagedIdentityCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    ManagedIdentityCredential(client_id="YOUR-USER-ASSIGNED-CLIENT-ID"),
    "https://ai.azure.com/.default",
)

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

DefaultAzureCredential Um denselben Code weiterhin lokal auszuführen, legen Sie die AZURE_CLIENT_ID Umgebungsvariable auf dem Azure Host auf die Client-ID der vom Benutzer zugewiesenen verwalteten Identität fest. DefaultAzureCredential liest diese Variable und wählt die übereinstimmende Identität aus.

Weitere Informationen finden Sie unter Verwaltete Identitäten für Azure-Ressourcen.

Aufrufen der Steuerelementebenen-API

In den vorherigen Beispielen wird die Datenebene aufgerufen, in der Sie Ableitungen ausführen. Verwaltungsvorgänge, z. B. das Auflisten der in einer Region verfügbaren Modelle, verwenden die Steuerungsebene. Die Steuerungsebene ist eine andere API mit einer anderen Tokengruppe: https://management.azure.com/.default anstelle von https://ai.azure.com/.default. Ein für eine Zielgruppe ausgestelltes Token funktioniert nicht mit dem anderen.

import requests
import json
from azure.identity import DefaultAzureCredential

region = "eastus"
token_credential = DefaultAzureCredential()
subscriptionId = "{YOUR-SUBSCRIPTION-ID}" 

token = token_credential.get_token('https://management.azure.com/.default')
headers = {'Authorization': 'Bearer ' + token.token}

url = f"https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{region}/models?api-version=2023-05-01"

response = requests.get(url, headers=headers)

data = json.loads(response.text)

print(json.dumps(data, indent=4))

Steuerungsebenenaufrufe benötigen eine Rolle, die Verwaltungsberechtigungen gewährt, z. B. Cognitive Services-Mitwirkender. Die Ableitungsrollen in " Rolle zuweisen " gewähren keinen Zugriff auf die Steuerungsebene.

Authentifizierungsfehler beheben

Symptom	Wahrscheinliche Ursache	Beheben
`401 Unauthorized`	Die Ressource verfügt nicht über eine benutzerdefinierte Unterdomäne, sodass sie entra-Token nicht akzeptieren kann.	Konfigurieren Sie eine benutzerdefinierte Unterdomäne , und verwenden Sie den `https://YOUR-RESOURCE-NAME.openai.azure.com` Endpunkt anstelle des regionalen Endpunkts.
`403 Forbidden` oder `PermissionDenied`	Die Identität hat keine Rolle für die Ressource, oder die Zuordnung wurde nicht weitergegeben.	Vergewissern Sie sich, dass sich die Rollenzuweisung auf der Azure OpenAI-Ressource befindet, warten Sie dann bis zu fünf Minuten, und wiederholen Sie den Vorgang.
`DefaultAzureCredential failed to retrieve a token`	Sie sind nicht lokal angemeldet, oder Sie sind beim falschen Mandanten angemeldet.	Führen Sie `az login --tenant YOUR-TENANT-ID` aus.
Funktioniert lokal, schlägt nach der Bereitstellung fehl	Die verwaltete Identität ist nicht aktiviert, oder die Rolle wurde Ihrem Benutzerkonto und nicht der Identität zugewiesen.	Aktivieren Sie die verwaltete Identität auf dem Host, und weisen Sie sie der Rolle zu.
Funktioniert lokal, schlägt in Azure mit einer vom Benutzer zugewiesenen Identität fehl.	Der Host verfügt über mehrere Identitäten, und es wurde keine angegeben.	Übergeben Sie die Client-ID, oder legen Sie sie auf dem Host fest `AZURE_CLIENT_ID` .
`404 Not Found` auf einem gültigen Endpunkt	Der `model` Wert stimmt nicht mit einem Bereitstellungsnamen überein.	Verwenden Sie Ihren Bereitstellungsnamen, der sich vom Modellnamen unterscheiden kann.

Feedback

War diese Seite hilfreich?

Last updated on 2026-08-04