Authentifier les demandes auprès des outils Foundry

Chaque demande adressée à Foundry Tools doit inclure un en-tête d’authentification. Cet en-tête passe une clé de ressource ou un jeton d’authentification qui sert à valider votre abonnement à un service ou à un groupe de services. Cet article présente trois façons d’authentifier une requête et les conditions de chaque méthode.

• S’authentifier avec une clé de ressource monoservice ou multiservice Foundry.
• S’authentifier avec un jeton.
• S’authentifier avec Microsoft Entra ID.

Prérequis

Avant d’effectuer une demande, vous avez besoin d’un abonnement Azure et d’une ressource Foundry. Si vous avez besoin d’une ressource Foundry, consultez le guide de création d’une ressource Foundry .

En-têtes d’authentification

Examinons rapidement les en-têtes d’authentification disponibles pour une utilisation avec Foundry Tools.

Authentifier avec une clé de ressource monoservice

La première option consiste à authentifier une demande avec une clé de ressource pour un service spécifique, comme Azure Translator. Les clés sont disponibles dans le portail Azure pour chaque ressource que vous avez créée. Accédez à votre ressource sur le portail Azure. La section Point de terminaison et clés se trouve dans la section Gestion des ressources. Copiez votre point de terminaison et votre clé d’accès, car vous aurez besoin de l’authentification de vos appels d’API. Vous pouvez utiliser soit KEY1, soit KEY2. Avoir toujours deux clés vous permet de faire pivoter et de régénérer en toute sécurité les clés sans provoquer d’interruption de service.

Pour utiliser une clé de ressource pour authentifier une requête, vous devez la passer sous la forme de l’en-tête Ocp-Apim-Subscription-Key. Il s’agit d’un exemple d’appel au service Azure Translator :

Voici un exemple d’appel au service Translator :

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

S’authentifier avec une clé de ressource Foundry

Vous pouvez utiliser une clé de ressource Foundry pour authentifier les demandes de plusieurs outils Foundry. Les informations d’identification d’authentification ne sont pas liées à un service spécifique. Consultez la tarification des outils Foundry pour plus d’informations sur la disponibilité régionale, les fonctionnalités prises en charge et la tarification.

La clé de ressource est fournie dans chaque requête sous la forme de l’en-tête Ocp-Apim-Subscription-Key.

Régions prises en charge

Lorsque vous utilisez la clé de ressource Foundry pour effectuer une requête api.cognitive.microsoft.com, vous devez inclure la région dans l’URL. Par exemple : westus.api.cognitive.microsoft.com.

Lorsque vous utilisez une clé de ressource Foundry avec Azure Translator, vous devez spécifier la région de ressource avec l’en-tête Ocp-Apim-Subscription-Region .

L’authentification des ressources Foundry est prise en charge dans ces régions :

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

Exemples de demandes

Il s’agit d’un exemple d’appel au service Azure Translator :

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

S’authentifier à l’aide d’une jeton d’accès

Certains outils Foundry acceptent et, dans certains cas, nécessitent un jeton d’accès. Les services suivants prennent actuellement en charge les jetons d’accès :

• API de traduction de texte
• Reconnaissance vocale : API transcription vocale
• Synthèse vocale : API de synthèse vocale

Les clés de ressources des services de fonderie et d'IA peuvent être échangées contre des jetons d'authentification. Les jetons d’authentification sont valides pour une durée de 10 minutes. Ils sont stockés au format JWT (JSON Web Token) et peuvent être interrogés par programmation à l’aide des bibliothèques JWT.

Les jetons d’accès sont incluses dans une requête sous la forme de l’en-tête Authorization. La valeur du jeton fournie doit être précédée de Bearer. Par exemple : Bearer YOUR_AUTH_TOKEN.

Exemples de demandes

Utilisez cette URL pour échanger une clé de ressource contre un jeton d’accès : 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"

Ces régions prennent en charge l’échange de jetons pour les ressources Foundry :

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

Après avoir obtenu un jeton d’accès, vous devez le passer dans chaque requête sous la forme de l’en-tête Authorization. Il s’agit d’un exemple d’appel au service Azure Translator :

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

S’authentifier avec Microsoft Entra ID

Dans les sections précédentes, nous vous avons montré comment vous authentifier à l’aide de clés API. Bien que ces clés fournissent un chemin rapide et facile pour démarrer le développement, elles ne suffisent pas dans les scénarios nécessitant un contrôle d’accès en fonction du rôle Azure (Azure RBAC). Examinons ce qui est nécessaire pour s’authentifier de manière plus sécurisée à l’aide de l’ID Microsoft Entra.

Dans les sections suivantes, vous allez utiliser l’environnement Azure Cloud Shell ou Azure CLI pour créer un sous-domaine, attribuer des rôles et obtenir un jeton du porteur pour appeler les outils Foundry. Si vous êtes bloqué, des liens sont fournis dans chaque section avec toutes les options disponibles pour chaque commande dans Azure Cloud Shell/Azure CLI.

Créer une ressource avec un sous-domaine personnalisé

La première étape consiste à créer un sous-domaine personnalisé. Si vous souhaitez utiliser une ressource Foundry existante qui n’a pas de nom de sous-domaine personnalisé, suivez les instructions fournies dans Les sous-domaines personnalisés des outils Foundry pour activer le sous-domaine personnalisé pour votre ressource.

1. Commencez par ouvrir Azure Cloud Shell. Ensuite, sélectionnez un abonnement :

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Ensuite, créez une ressource Foundry avec un sous-domaine personnalisé. Le nom de sous-domaine doit être globalement unique et ne peut pas inclure de caractères spéciaux, comme : « . », « ! », « , ».

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

3. Si l’opération réussit, le point de terminaison doit afficher le nom du sous-domaine unique pour votre ressource.

Attribuer un rôle à un principal de service

Maintenant que vous disposez d’un sous-domaine personnalisé associé à votre ressource, vous devez affecter un rôle à un principal du service.

1. Tout d’abord, nous allons inscrire une application Microsoft Entra.

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

   Vous aurez besoin de l’ApplicationId à l’étape suivante.

2. Ensuite, vous devez créer un principal du service pour l’application Microsoft Entra.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Remarque

   Si vous inscrivez une application dans le portail Azure, cette étape est effectuée pour vous.

3. La dernière étape consiste à affecter le rôle « Utilisateur Cognitive Services » au principal du service (délimité à la ressource). En affectant un rôle, vous accordez au principal du service l’accès à cette ressource. Vous pouvez accorder au même principal du service l’accès à plusieurs ressources de votre abonnement.

   Remarque

   L’ObjectId du principal du service est utilisé, et non pas l’ObjectId de l’application. Le ACCOUNT_ID sera l’ID de ressource Azure de la ressource Foundry que vous avez créée. Vous trouverez l’ID de ressource Azure à partir des « propriétés » de la ressource dans le portail Azure.

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

Exemple de requête

Dans cet exemple, un mot de passe est utilisé pour authentifier le principal du service. Le jeton fourni est ensuite utilisé pour appeler l’API Azure Vision.

1. Obtenez votre TenantId :

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

2. Obtenez un jeton :

   $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
   

   Remarque

   Chaque fois que vous utilisez des mots de passe dans un script, l’option la plus sécurisée consiste à utiliser le module Gestion des secrets PowerShell et à l’intégrer à une solution telle qu’Azure Key Vault.

3. Appelez l’API Azure Vision :

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

Le principal du service peut également être authentifié avec un certificat. En plus du principal du service, l’utilisateur principal est également pris en charge en ayant des autorisations déléguées via une autre application Microsoft Entra. Dans ce cas, au lieu de mots de passe ou de certificats, les utilisateurs sont invités à fournir une authentification à deux facteurs lors de l’acquisition du jeton.

Autoriser l'accès aux identités managées

Foundry Tools prend en charge l’authentification Microsoft Entra avec des identités managées pour les ressources Azure. Les identités gérées pour les ressources Azure peuvent autoriser l’accès aux ressources Foundry à l’aide des informations d’identification Microsoft Entra à partir d’applications s’exécutant dans des machines virtuelles Azure, des applications fonctionnelles, des jeux à échelle de machines virtuelles et d’autres services. En utilisant des identités managées pour les ressources Azure avec l’authentification Microsoft Entra, vous pouvez éviter de stocker des informations d’identification avec vos applications qui s’exécutent dans le cloud.

Activer les identités managées sur une machine virtuelle

Avant de pouvoir utiliser des identités managées pour les ressources Azure pour autoriser l’accès aux ressources Foundry à partir de votre machine virtuelle, vous devez activer les identités managées pour les ressources Azure sur la machine virtuelle. Pour savoir comment activer des identités managées pour les ressources Azure, consultez :

• portail Azure
• Azure PowerShell
• Azure CLI
• Modèle Azure Resource Manager
• Bibliothèques clientes Azure Resource Manager

Pour plus d’informations sur les identités managées, consultez Identités managées pour les ressources Azure.

Accès sécurisé aux informations d’identification avec Azure Key Vault

Vous pouvez utiliser Azure Key Vault pour développer en toute sécurité des applications Microsoft Foundry. Key Vault vous permet de stocker vos informations d’identification d’authentification dans le cloud et réduit les risques de fuite accidentelle des secrets. En effet, vous n’enregistrez pas d’informations de sécurité dans votre application.

L’authentification est effectuée via Microsoft Entra ID. L’autorisation peut être assurée par l’intermédiaire du mécanisme de contrôle d’accès en fonction du rôle Azure (Azure RBAC) ou d’une stratégie d’accès à Key Vault. Vous pouvez utiliser Azure RBAC pour la gestion des coffres et l’accès aux données stockées dans un coffre, alors que la stratégie d’accès au coffre de clés ne peut être utilisée que lors d’une tentative d’accès aux données stockées dans un coffre.

Contenu connexe

• Qu’est-ce que les outils Foundry ?
• Tarification des outils Foundry
• Sous-domaines personnalisés