Authentifizieren von Anforderungen an Azure Cognitive Services

Jede Anforderung an Azure Cognitive Service muss einen Authentifizierungsheader enthalten. Dieser Header übergibt einen Abonnementschlü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.

Voraussetzungen

Damit Sie eine Anforderung übermitteln können, benötigen Sie ein Azure-Konto und ein Azure Cognitive 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 der folgenden Anleitung in wenigen Minuten startbereit: Erstellen eines Cognitive Services-Kontos für Azure.

Sie können Ihren Abonnementschlüssel über das Azure-Portal abrufen, nachdem Sie Ihr Konto erstellt haben.

Authentifizierungsheader

Betrachten wir zunächst kurz die verfügbaren Authentifizierungsheader für die Verwendung mit Azure Cognitive Services.

Header BESCHREIBUNG
Ocp-Apim-Subscription-Key Verwenden Sie diesen Header für die Authentifizierung mit einem Abonnementschlüssel für einen bestimmten Dienst oder für mehrere Dienste.
Ocp-Apim-Subscription-Region Dieser Header ist nur bei Verwendung eines Schlüssels für ein Abonnement für mehrere Dienste mit dem Translator-Dienst erforderlich. Verwenden Sie diesen Header, um die Abonnementregion anzugeben.
Authorization 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 Schlüssel für ein Abonnement für einen einzelnen Dienst

Die erste Option zum Authentifizieren einer Anforderung nutzt einen Abonnementschlüssel für einen bestimmten Dienst wie Translator. Die Schlüssel stehen im Azure-Portal für jede Ressource, die Sie erstellt haben, zur Verfügung. Wenn Sie einen Abonnementschlüssel zum Authentifizieren einer Anforderung verwenden möchten, müssen Sie diesen als Ocp-Apim-Subscription-Key-Header übergeben.

Diese Beispielanforderungen veranschaulichen die Verwendung des Ocp-Apim-Subscription-Key-Headers. Wenn Sie dieses Beispiel verwenden möchten, müssen Sie einen gültigen Abonnementschlüssel einfügen.

Dies ist ein Beispielaufruf der Bing-Websuche-API:

curl -X GET 'https://api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

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

Das folgende Video veranschaulicht die Verwendung eines Cognitive Services-Schlüssels.

Authentifizieren mit einem Schlüssel für ein Abonnement für mehrere Dienste

Warnung

Derzeit unterstützt der Schlüssel für mehrere Dienste Folgendes nicht: QnA Maker, Immersive Reader, Personalisierung und Anomalieerkennung.

Bei dieser Option wird ebenfalls ein Abonnementschlüssel zum Authentifizieren von Anforderungen verwendet. Der Hauptunterschied besteht darin, dass der Abonnementschlüssel nicht an einen bestimmten Dienst gebunden ist, sondern dass ein einzelner Schlüssel zum Authentifizieren von Anforderungen für mehrere Cognitive Services-Dienste verwendet werden kann. Weitere Informationen zur regionalen Verfügbarkeit, den unterstützten Funktionen und den Preisen finden Sie unter Cognitive Services – Preise.

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

Demonstration eines Abonnementschlüssels für mehrere Dienste für Cognitive Services

Unterstützte Regionen

Wenn Sie für eine Anforderung an api.cognitive.microsoft.com einen Schlüssel zu einem Abonnement für mehrere Dienste verwenden, müssen Sie die Region in die URL einschließen. Beispiel: westus.api.cognitive.microsoft.com.

Wenn Sie einen Schlüssel für ein Abonnement für mehrere Dienste mit dem Translator-Dienst verwenden, müssen Sie die Region des Abonnements im Ocp-Apim-Subscription-Region-Header angeben.

Die Authentifizierung 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 der Bing-Websuche-API:

curl -X GET 'https://YOUR-REGION.api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

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 '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 Cognitive Services akzeptieren ein Zugriffstoken (einige erfordern es auch). Derzeit werden Zugriffstoken von folgenden Diensten unterstützt:

  • Textübersetzungs-API
  • Speech Services: Sprache-zu-Text-API
  • Speech Services: Text-zu-Sprache-API

Hinweis

QnA Maker verwendet ebenfalls den Autorisierungsheader, erfordert allerdings einen Endpunktschlüssel. Weitere Informationen finden Sie unter QnA Maker: Erhalten einer Antwort von der Wissensdatenbank.

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 Schlüssel zu Abonnements für einen Dienst als auch die zu Abonnements für mehrere Dienste können mit 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 Abonnementschlü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 Translator-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

Authentifizieren mit Azure Active Directory

Wichtig

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

In den vorherigen Abschnitten haben wir Ihnen gezeigt, wie die Authentifizierung bei Azure Cognitive Services 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 über Azure Active Directory (Azure AD) 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 Cognitive Services 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.

Erstellen einer Ressource mit einer benutzerdefinierten Unterdomäne

Der erste Schritt besteht darin, eine benutzerdefinierte Unterdomäne zu erstellen. Wenn Sie eine vorhandene Cognitive Services-Ressource verwenden möchten, die nicht über einen benutzerdefinierten Unterdomänennamen verfügt, befolgen Sie die Anweisungen in Benutzerdefinierte Unterdomänennamen für Cognitive Services, 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 Cognitive 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. Als Erstes registrieren Sie eine Azure AD-Anwendung.

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

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

  2. Als Nächstes müssen Sie für die AAD-Anwendung einen Dienstprinzipal 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 entspricht der Azure-Ressourcen-ID des Cognitive 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:

    Hinweis

    Wenn Sie Azure Cloud Shell verwenden, ist die SecureClientSecret-Klasse nicht verfügbar.

    $authContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList "https://login.windows.net/<TENANT_ID>"
    $secureSecretObject = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.SecureClientSecret" -ArgumentList $SecureStringPassword   
    $clientCredential = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential" -ArgumentList $app.ApplicationId, $secureSecretObject
    $token=$authContext.AcquireTokenAsync("https://cognitiveservices.azure.com/", $clientCredential).Result
    $token
    

  1. Aufrufen der Maschinelles Sehen-API:
    $url = $account.Endpoint+"vision/v1.0/models"
    $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"=$token.CreateAuthorizationHeader()} -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 Azure AD-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

Cognitive Services unterstützen die Azure AD-Authentifizierung (Azure Active Directory) mit verwalteten Identitäten für Azure-Ressourcen. Sie können verwaltete Identitäten für Azure-Ressourcen verwenden, um den Zugriff auf Cognitive Services-Ressourcen mithilfe von Azure AD-Anmeldeinformationen über Anwendungen zu autorisieren, die auf virtuellen Azure-Computern, in Funktions-Apps, in VM-Skalierungsgruppen und anderen Diensten ausgeführt werden. Durch Verwendung von verwalteten Identitäten für Azure-Ressourcen zusammen mit der Azure AD-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 Cognitive 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:

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 Cognitive 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 Azure Active Directory. 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.

Weitere Informationen