Authentifizieren von Anforderungen an Azure KI Services

Jede Anforderung an Azure KI Services-Instanzen 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 mit einem Ressourcenschlüssel für einen Dienst oder mehrere Dienste
• Authentifizieren mit einem Token
• Authentifizieren mit Microsoft Entra ID

Voraussetzungen

Damit Sie eine Anforderung übermitteln können, benötigen Sie ein Azure-Konto und ein Azure KI Services-Abonnement. Wenn Sie bereits über ein Konto verfügen, können Sie mit dem nächsten Abschnitt fortfahren. Wenn Sie noch kein Konto haben, sind Sie mit dem folgenden Leitfaden in wenigen Minuten startbereit: Erstellen einer Azure KI Services-Ressource.

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.

Authentifizierungsheader

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

Header	BESCHREIBUNG
Ocp-Apim-Subscription-Key	Verwenden Sie diesen Header für die Authentifizierung mit einem Ressourcenschlüssel für einen bestimmten Dienst oder für mehrere Dienste.
Ocp-Apim-Subscription-Region	Dieser Header ist nur bei Verwendung eines Ressourcenschlüssels für mehrere Dienste mit dem Azure KI Übersetzer-Dienst erforderlich. 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 Ressourcenschlüssel für mehrere Dienste

Sie können einen Ressourcenschlüssel für mehrere Dienste verwenden, um Anforderungen zu authentifizieren. Der Hauptunterschied besteht darin, dass ein Ressourcenschlüssel für mehrere Dienste nicht an einen bestimmten Dienst gebunden ist, sondern ein einzelner Schlüssel zum Authentifizieren von Anforderungen für mehrere Azure KI Services-Instanzen verwendet werden kann. 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 einen Ressourcenschlüssel für mehrere Azure KI Übersetzer-Dienste verwenden, müssen Sie die Region in die URL einschließen. Beispiel: westus.api.cognitive.microsoft.com

Wenn Sie einen Ressourcenschlüssel für mehrere Dienste mit Azure KI Übersetzer verwenden, müssen Sie die Ressourcenregion mit dem Ocp-Apim-Subscription-Region-Header angeben.

Die Ressourcenauthentifizierung für mehrere Dienste wird in den folgenden 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 Lauf der Zeit ändern. Sehen Sie in der API-Referenz zu einem Dienst nach, bevor Sie diese Authentifizierungsmethode verwenden.

Sowohl Ressourcenschlüssel für einen Dienst als auch Ressourcenschlüssel für mehrere Dienste können für Authentifizierungstokens 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 für mehrere Dienste unterstützen den Tokenaustausch:

• 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 wurde erläutert, wie die Authentifizierung bei Azure KI Services-Instanzen mit einem Abonnementschlüssel für einen einzelnen oder mehrere Dienste funktioniert. Diese Schlüssel ermöglichen zwar einen schnellen und einfachen Einstieg in die Entwicklung, eignen sich aber nicht für komplexere Szenarien, die eine rollenbasierte Zugriffssteuerung von Azure (Azure RBAC) erfordern. Sehen wir uns an, was für die Authentifizierung mithilfe von 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 Azure KI Services-Ressource verwenden möchten, die keinen benutzerdefinierten Unterdomänennamen hat, befolgen Sie die Anweisungen unter Wie wirkt sich dies auf vorhandene Ressourcen aus?, um die benutzerdefinierte Unterdomäne 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. Als Nächstes erstellen Sie eine Azure KI Services-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. „ACCOUNT_ID“ entspricht der Azure-Ressourcen-ID des Azure KI Services-Kontos, das Sie erstellt haben. Die Azure-Ressourcen-ID finden Sie unter den Eigenschaften der jeweiligen 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 für den Aufruf der Maschinelles Sehen-API verwendet.

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 Maschinelles Sehen-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. Sie können verwaltete Identitäten für Azure-Ressourcen verwenden, um den Zugriff auf Azure KI Services-Ressourcen mithilfe von Microsoft Entra-Anmeldeinformationen über Anwendungen zu autorisieren, die auf Azure-VMs, in Funktionsapps, in 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 von verwalteten Identitäten auf einem virtuellen Computer

Damit Sie verwaltete Identitäten für Azure-Ressourcen zum Autorisieren des Zugriffs auf Azure KI Services-Ressourcen über Ihren virtuellen Computer verwenden können, müssen Sie verwaltete Identitäten für Azure-Ressourcen auf dem virtuellen Computer aktivieren. Informationen zum Aktivieren von verwalteten 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 KI Services-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.

Siehe auch

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