Authentifizieren von Anforderungen an Azure KI Services

Jede Anforderung an Azure AI-Dienste muss einen Authentifizierungsheader enthalten. Dieser Header übergibt einen Ressourcenschlüssel oder ein Authentifizierungstoken, mit dem Ihr Abonnement für einen Dienst oder eine Gruppe von Diensten überprüft wird. In diesem Artikel lernen Sie die drei Möglichkeiten zum Authentifizieren von Anforderungen und die jeweiligen Voraussetzungen kennen.

• Authentifizieren Sie sich mit einem Ressourcenschlüssel für einen Dienst oder mehrere AI Foundry-Dienste.
• Authentifizieren Sie sich mit einem Token.
• Authentifizieren Sie sich mit Microsoft Entra ID.

Voraussetzungen

Bevor Sie eine Anforderung stellen, benötigen Sie ein Azure-Abonnement und eine AI Foundry-Ressource. Wenn Sie eine AI Foundry-Ressource benötigen, lesen Sie den Leitfaden Erstellen einer AI Foundry-Ressource.

Authentifizierungsheader

Sehen Sie sich zunächst die verfügbaren Authentifizierungsheader für die Verwendung mit Azure KI Services an.

Kopfzeile	BESCHREIBUNG
Ocp-Apim-Subscription-Key	Verwenden Sie diesen Header, um sich mit einem Ressourcenschlüssel für einen bestimmten Dienst oder einen KI Foundry-Ressourcenschlüssel zu authentifizieren.
Ocp-Apim-Subscription-Region	Dieser Header ist nur erforderlich, wenn sie einen AI Foundry-Ressourcenschlüssel mit dem Azure AI Translator-Dienst verwenden. Verwenden Sie diesen Header, um die Ressourcenregion anzugeben.
Autorisierung	Verwenden Sie diesen Header, wenn Sie ein Zugriffstoken verwenden. Die Schritte zum Ausführen eines Tokenaustauschs werden in den folgenden Abschnitten beschrieben. Der angegebene Wert weist folgendes Format auf: Bearer <TOKEN>.

Authentifizieren mit einem Ressourcenschlüssel für einen Dienst

Bei der ersten Option zum Authentifizieren einer Anforderung wird ein Ressourcenschlüssel für einen bestimmten Dienst (z. B. Azure KI Übersetzer) verwendet. Die Schlüssel stehen im Azure-Portal für jede Ressource, die Sie erstellt haben, zur Verfügung. Wechseln Sie zu Ihrer Ressource im Azure-Portal. Den Abschnitt Schlüssel und Endpunkt finden Sie im Abschnitt Ressourcenverwaltung. Kopieren Sie die Werte für Endpunkt und Zugriffsschlüssel, da Sie beide für die Authentifizierung Ihrer API-Aufrufe benötigen. Sie können KEY1 oder KEY2 verwenden. Wenn Sie jederzeit zwei Schlüssel zur Verfügung haben, können Sie die Schlüssel auf sichere Weise rotieren und neu generieren, ohne Dienstunterbrechungen zu verursachen.

Wenn Sie einen Ressourcenschlüssel zum Authentifizieren einer Anforderung verwenden möchten, müssen Sie diesen als Ocp-Apim-Subscription-Key-Header übergeben. Dies ist ein Beispielaufruf des Azure KI Übersetzer-Diensts:

Dies ist ein Beispielaufruf des Translator-Diensts:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Authentifizieren mit einem KI Foundry-Ressourcenschlüssel

Sie können einen AI Foundry-Ressourcenschlüssel verwenden, um Anforderungen für mehrere Azure AI-Dienste zu authentifizieren. Die Authentifizierungsanmeldeinformationen sind nicht an einen bestimmten Dienst gebunden. Weitere Informationen zur regionalen Verfügbarkeit, den unterstützten Features und den Preisen finden Sie unter Azure KI Services – Preise.

Der Ressourcenschlüssel wird in jeder Anforderung als Ocp-Apim-Subscription-Key-Header bereitgestellt.

Unterstützte Regionen

Wenn Sie für eine Anforderung an api.cognitive.microsoft.com den Schlüssel der AI Foundry-Ressource verwenden, müssen Sie die Region in die URL einschließen. Beispiel: westus.api.cognitive.microsoft.com

Wenn Sie einen AI Foundry-Ressourcenschlüssel mit Azure AI Translator verwenden, müssen Sie den Ressourcenbereich mit dem Ocp-Apim-Subscription-Region Header angeben.

Die AI Foundry-Ressourcenauthentifizierung wird in diesen Regionen unterstützt:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2
• francecentral
• koreacentral
• northcentralus
• southafricanorth
• uaenorth
• switzerlandnorth

Beispielanforderungen

Dies ist ein Beispielaufruf des Azure KI Übersetzer-Diensts:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Ocp-Apim-Subscription-Region: YOUR_SUBSCRIPTION_REGION' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Authentifizieren mit einem Zugriffstoken

Einige Azure KI Services-Instanzen akzeptieren ein Zugriffstoken (einige erfordern es auch). Derzeit werden Zugriffstoken von folgenden Diensten unterstützt:

• Textübersetzungs-API
• Speech Services: Spracherkennungs-API
• Speech Services: Sprachsynthese-API

Warnung

Die Dienste, die Zugriffstoken unterstützen, können sich im Laufe der Zeit ändern. Überprüfen Sie daher die API-Referenz für einen Dienst, bevor Sie diese Authentifizierungsmethode verwenden.

KI Foundry- und KI-Dienste-Ressourcenschlüssel können für Authentifizierungstoken ausgetauscht werden. Authentifizierungstoken sind zehn Minuten lang gültig. Sie werden im JSON-Webtokenformat (JWT) gespeichert und können programmgesteuert mithilfe der JWT-Bibliotheken abgefragt werden.

Zugriffstoken werden als Authorization-Header in eine Anforderung eingefügt. Dem bereitgestellten Tokenwert muss Bearer vorangestellt werden, z.B.: Bearer YOUR_AUTH_TOKEN.

Beispielanforderungen

Verwenden Sie diese URL, um einen Ressourcenschlüssel gegen ein Zugriffstoken zu tauschen: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken.

curl -v -X POST \
"https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Diese Regionen unterstützen den Tokenaustausch für KI Foundry-Ressourcen:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2

Nach dem Erhalt eines Zugriffstokens müssen Sie dieses in jeder Anforderung als Authorization-Header übergeben. Dies ist ein Beispielaufruf des Azure KI Übersetzer-Diensts:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Authentifizierung mit Microsoft Entra ID

Wichtig

Die Microsoft Entra-Authentifizierung muss stets mit dem Namen der benutzerdefinierten Unterdomäne Ihrer Azure-Ressource verwendet werden. Regionale Endpunkte unterstützen die Microsoft Entra-Authentifizierung nicht.

In den vorherigen Abschnitten haben wir Ihnen gezeigt, wie Sie sich mithilfe von API-Schlüsseln authentifizieren. Diese Schlüssel bieten zwar einen schnellen und einfachen Weg, um mit der Entwicklung zu beginnen, sie fallen jedoch in Szenarien kurz, die eine rollenbasierte Azure-Zugriffssteuerung (Azure RBAC) erfordern. Sehen wir uns an, was für eine sicherere Authentifizierung mithilfe der Microsoft Entra-ID erforderlich ist.

In den folgenden Abschnitten verwenden Sie entweder die Azure Cloud Shell-Umgebung oder die Azure CLI, um eine Unterdomäne zu erstellen, Rollen zuzuweisen und ein Bearertoken für den Aufruf der Azure KI Services-Instanzen abzurufen. Falls Sie einmal nicht weiterkommen, finden Sie in jedem Abschnitt Links mit sämtlichen verfügbaren Optionen für jeden Befehl in der Azure Cloud Shell bzw. Azure CLI.

Wichtig

Wenn Ihre Organisation die Authentifizierung über Microsoft Entra ID durchführt, sollten Sie die lokale Authentifizierung (Authentifizierung mit Schlüsseln) deaktivieren, damit die Benutzer in der Organisation immer Microsoft Entra ID verwenden müssen.

Erstellen einer Ressource mit einer benutzerdefinierten Unterdomäne

Der erste Schritt besteht darin, eine benutzerdefinierte Unterdomäne zu erstellen. Wenn Sie eine vorhandene AI Foundry-Ressource verwenden möchten, die keinen benutzerdefinierten Unterdomänennamen aufweist, befolgen Sie die Anweisungen in benutzerdefinierten Azure AI-Diensten, um benutzerdefinierte Unterdomänen für Ihre Ressource zu aktivieren.

1. Öffnen Sie als Erstes die Azure Cloud Shell. Wählen Sie dann ein Abonnement aus:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Erstellen Sie als Nächstes eine AI Foundry-Ressource mit einer benutzerdefinierten Unterdomäne. Der Name der Unterdomäne muss global eindeutig sein und darf einige Zeichen nicht enthalten, wie z.B. „.“, „!“ oder „,“.

   $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
   

3. Wenn die Erstellung erfolgreich verläuft, zeigt der Endpunkt den Unterdomänennamen an, der für Ihre Ressource eindeutig ist.

Zuweisen einer Rolle zu einem Dienstprinzipal

Nachdem Sie nun über eine Unterdomäne verfügen, die Ihrer Ressource zugeordnet ist, müssen Sie einem Dienstprinzipal eine Rolle zuweisen.

Hinweis

Denken Sie daran, dass die Weitergabe von Azure-Rollenzuweisungen bis zu fünf Minuten dauern kann.

1. Zunächst registrieren wir eine Microsoft Entra-Anwendung.

   $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force
   
   $app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword
   

   Im nächsten Schritt benötigen Sie die ApplicationId.

2. Als Nächstes müssen Sie einen Dienstprinzipal für die Microsoft Entra-Anwendung erstellen.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Hinweis

   Wenn Sie eine Anwendung im Azure-Portal registrieren, wird dieser Schritt für Sie ausgeführt.

3. Der letzte Schritt besteht darin, dem Dienstprinzipal (im Bereich der Ressource) die Rolle „Cognitive Services-Benutzer“ zuzuweisen. Durch Zuweisen einer Rolle gewähren Sie dem Dienstprinzipal Zugriff auf diese Ressource. Sie können einem Dienstprinzipal Zugriff auf mehrere Ressourcen in Ihrem Abonnement gewähren.

   Hinweis

   Es wird die ObjectId des Dienstprinzipals verwendet, nicht die ObjectId der Anwendung. Die ACCOUNT_ID ist die Azure-Ressourcen-ID der von Ihnen erstellten AI Foundry-Ressource. Die Azure-Ressourcen-ID finden Sie unter "Eigenschaften" der Ressource im Azure-Portal.

   New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
   

Beispiel für eine Anforderung

In diesem Beispiel wird ein Kennwort für die Authentifizierung des Dienstprinzipals verwendet. Das bereitgestellte Token wird dann verwendet, um die Azure AI Vision-API aufzurufen.

1. Rufen Sie Ihre TenantId ab:

   $context=Get-AzContext
   $context.Tenant.Id
   

2. Rufen Sie ein Token ab:

   $tenantId = $context.Tenant.Id
   $clientId = $app.ApplicationId
   $clientSecret = "<YOUR_PASSWORD>"
   $resourceUrl = "https://cognitiveservices.azure.com/"
   
   $tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
   $body = @{
       grant_type    = "client_credentials"
       client_id     = $clientId
       client_secret = $clientSecret
       resource      = $resourceUrl
   }
   
   $responseToken = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body
   $accessToken = $responseToken.access_token
   

   Hinweis

   Wenn Sie Kennwörter in einem Skript verwenden, besteht die sicherste Option darin, das SecretsManagement-Modul von PowerShell zu nutzen und mit einer Lösung wie Azure Key Vault zu integrieren.

3. Aufrufen der Azure AI Vision-API:

   $url = $account.Endpoint+"vision/v1.0/models"
   $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"="Bearer $accessToken"} -Verbose
   $result | ConvertTo-Json
   

Alternativ dazu kann der Dienstprinzipal auch mit einem Zertifikat authentifiziert werden. Neben dem Dienstprinzipal wird auch der Benutzerprinzipal unterstützt, indem Berechtigungen durch eine andere Microsoft Entra-Anwendung delegiert werden. In diesem Fall verwenden Benutzer keine Kennwörter oder Zertifikate, sondern werden beim Abrufen des Tokens zur zweistufigen Authentifizierung aufgefordert.

Autorisieren des Zugriffs auf verwaltete Identitäten

Azure KI Services unterstützt die Microsoft Entra-Authentifizierung mit verwalteten Identitäten für Azure-Ressourcen. Verwaltete Identitäten für Azure-Ressourcen können den Zugriff auf KI Foundry-Ressourcen mithilfe von Microsoft Entra-Anmeldeinformationen von Anwendungen autorisieren, die in virtuellen Azure-Computern (VMs), Funktions-Apps, VM-Skalierungsgruppen und anderen Diensten ausgeführt werden. Durch Verwendung von verwalteten Identitäten für Azure-Ressourcen zusammen mit der Microsoft Entra-Authentifizierung können Sie vermeiden, dass Anmeldeinformationen mit den in der Cloud ausgeführten Anwendungen gespeichert werden.

Aktivieren verwalteter Identitäten auf einem virtuellen Computer (VM)

Bevor Sie verwaltete Identitäten für Azure-Ressourcen verwenden können, um den Zugriff auf KI Foundry-Ressourcen von Ihrer VM zu autorisieren, müssen Sie verwaltete Identitäten für Azure-Ressourcen auf dem virtuellen Computer aktivieren. Informationen zum Aktivieren verwalteter Identitäten für Azure-Ressourcen finden Sie unter:

• Azure-Portal
• Azure PowerShell
• Azure-Befehlszeilenschnittstelle
• Azure Resource Manager-Vorlage
• Azure Resource Manager-Clientbibliotheken

Weitere Informationen zu verwalteten Identitäten finden Sie unter Was sind verwaltete Identitäten für Azure-Ressourcen?.

Verwenden des Azure-Schlüsseltresors zum sicheren Zugriff auf Anmeldeinformationen

Sie können Azure Key Vault verwenden , um Azure AI Foundry-Anwendungen sicher zu entwickeln. Key Vault ermöglicht es Ihnen, Ihre Authentifizierungsanmeldeinformationen in der Cloud zu speichern, und verringert das Risiko, dass Geheimnisse versehentlich weitergegeben werden, da Sie Sicherheitsinformationen nicht in Ihrer Anwendung speichern.

Die Authentifizierung erfolgt über Microsoft Entra ID. Für die Autorisierung kann die rollenbasierte Zugriffssteuerung in Azure (Azure RBAC) oder eine Key Vault-Zugriffsrichtlinie verwendet werden. Azure RBAC kann sowohl für die Verwaltung der Tresore als auch für den Zugriff auf in einem Tresor gespeicherte Daten verwendet werden. Die Schlüsseltresor-Zugriffsrichtlinie kann hingegen nur verwendet werden, wenn versucht wird, auf in einem Tresor gespeicherte Daten zuzugreifen.

Zugehöriger Inhalt

• Was sind Azure KI Services?
• Azure KI Services – Preise
• Benutzerdefinierte Unterdomänen