Authentifizieren von Anforderungen an Foundry-Tools

Jede Anforderung an Foundry Tools 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 Einzeldienst-Ressourcenschlüssel oder einem Foundry-Multidienst-Ressourcenschlüssel.
• 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 Foundry-Ressource. Wenn Sie eine Foundry-Ressource benötigen, lesen Sie den Leitfaden zum Erstellen einer Foundry-Ressource .

Authentifizierungsheader

Sehen Sie sich zunächst die verfügbaren Authentifizierungsheader für die Verwendung mit Foundry Tools an.

Authentifizieren mit einem Ressourcenschlüssel für einen Dienst

Die erste Option besteht darin, eine Anforderung mit einem Ressourcenschlüssel für einen bestimmten Dienst wie Azure Translator zu authentifizieren. 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 an den Azure Translator-Dienst:

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 Foundry-Ressourcenschlüssel

Sie können einen Foundry-Ressourcenschlüssel verwenden, um Anforderungen für mehrere Foundry-Tools zu authentifizieren. Die Authentifizierungsanmeldeinformationen sind nicht an einen bestimmten Dienst gebunden. Informationen zur regionalen Verfügbarkeit, unterstützten Features und Preisen finden Sie unter Foundry Tools 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 Foundry-Ressource verwenden, müssen Sie die Region in die URL einschließen. Beispiel: westus.api.cognitive.microsoft.com.

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

Die 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 an den Azure Translator-Dienst:

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 Foundry Tools akzeptieren, und in einigen Fällen ist ein Zugriffstoken erforderlich. Derzeit werden Zugriffstoken von folgenden Diensten unterstützt:

• Textübersetzungs-API
• Speech: Sprache-in-Text-API
• Sprachausgabe: Text-zu-Sprache-API

Die Ressourcenschlüssel von Foundry- und KI-Diensten können gegen 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 auszutauschen: 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 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 an den Azure Translator-Dienst:

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

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 abzurufen, um die Foundry Tools aufzurufen. 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 Foundry-Ressource verwenden möchten, die keinen benutzerdefinierten Unterdomänennamen hat, befolgen Sie die Anweisungen in den benutzerdefinierten Unterdomänen der Foundry Tools, 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 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.

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 Gießereiressource, die Sie erstellt haben. 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 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 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

Foundry Tools unterstützen die Microsoft Entra-Authentifizierung mit verwalteten Identitäten für Azure-Ressourcen. Verwaltete Identitäten für Azure-Ressourcen können den Zugriff auf Foundry-Ressourcen mithilfe von Microsoft Entra-Anmeldeinformationen von Anwendungen autorisieren, die auf 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 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 Microsoft 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.

Verwandte Inhalte

• Was sind Foundry Tools?
• Preise für Foundry Tools
• Benutzerdefinierte Unterdomänen