Authentifier les requêtes auprès d’Azure AI services

Article
10/28/2023

Chaque demande adressée à un service Azure AI 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.

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

Prérequis

Avant de pouvoir adresser une requête, vous devez disposer d’un compte Azure et d’un abonnement Azure AI services. Si vous avez déjà un compte, passez à la section suivante. Si vous n’avez pas de compte, ce guide va vous aider à en créer un en quelques minutes : Créer une ressource multiservice.

Vous pouvez obtenir votre clé de ressource sur le portail Azure après la création de votre compte.

En-têtes d’authentification

Passons rapidement en revue les en-têtes d’authentification disponibles en vue d’une utilisation avec Azure AI services.

En-tête	Description
Ocp-Apim-Subscription-Key	Utilisez cet en-tête pour authentifier une requête avec une clé de ressource à un service spécifique ou une clé de ressource multiservice.
Ocp-Apim-Subscription-Region	Cet en-tête n’est nécessaire que si vous utilisez une clé de ressource multiservice avec le service Traducteur. Utilisez cet en-tête pour spécifier la région de la ressource.
Autorisation	Utilisez cet en-tête si vous utilisez un jeton d’accès. Les étapes à suivre pour effectuer un échange de jeton sont détaillées dans les sections suivantes. La valeur fournie est au format suivant : `Bearer <TOKEN>`.

Authentifier avec une clé de ressource monoservice

La première option consiste à authentifier une requête avec une clé de ressource pour un service spécifique, tel que Traducteur. Les clés sont disponibles dans le portail Azure pour chaque ressource que vous avez créée. 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.

Ces exemples de demandes montrent comment utiliser l’en-tête Ocp-Apim-Subscription-Key. Si vous utilisez ces exemples, n’oubliez pas d’inclure une clé de ressource valide.

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

La vidéo suivante montre l’utilisation d’une clé Azure AI services.

Authentifier avec une clé de ressource multiservice

Vous pouvez utiliser une clé de ressource multiservice pour authentifier les requêtes. La principale différence tient au fait qu’une clé de ressource n’est pas liée à un service spécifique. Vous pouvez ainsi utiliser une seule clé pour authentifier des requêtes auprès de plusieurs services Azure AI services. Pour plus d’informations sur la disponibilité régionale, les fonctionnalités prises en charge et les tarifs, consultez les tarifs d’Azure AI services.

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

Quand vous utilisez la clé de ressource multiservice pour adresser 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 multiservice avec Azure AI Traducteur, vous devez spécifier la région de la ressource avec l’en-tête Ocp-Apim-Subscription-Region.

L’authentification multiservice 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

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 '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 services Azure AI services 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
Services Speech : API de reconnaissance vocale
Services Speech : API de synthèse vocale

Notes

QnA Maker utilise également l’en-tête Authorization, mais nécessite une clé de point de terminaison. Pour plus d’informations, consultez QnA Maker : Obtenir des réponses à partir de la base de connaissances.

Avertissement

Les services qui prennent en charge les jetons d’accès peuvent changer au fil du temps. Pensez donc à consulter la référence sur l’API d’un service avant d’utiliser cette méthode d’authentification.

Vous pouvez échanger les clés de ressource monoservice et multiservice 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 multiservices prennent en charge l’échange de jeton :

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. 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 '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

Important

L’authentification Microsoft Entra doit toujours être utilisée avec le nom de sous-domaine personnalisé de votre ressource Azure. Les Points de terminaison régionaux ne prennent pas en charge l’authentification Microsoft Entra.

Dans les sections précédentes, nous vous avons montré comment vous authentifier auprès d’Azure AI services en utilisant une clé d’abonnement monoservice ou multiservice. Bien que ces clés offrent un moyen simple et rapide de démarrer le développement, elles ne conviennent pas dans des scénarios plus complexes qui nécessitent le contrôle d’accès en fonction du rôle Azure (Azure RBAC). Voyons ce qui est nécessaire pour s’authentifier en tirant parti de Microsoft Entra ID.

Dans les sections suivantes, vous allez utiliser l’environnement Azure Cloud Shell ou Azure CLI pour créer un sous-domaine, affecter des rôles et obtenir un jeton de porteur pour appeler Azure AI services. 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.

Important

Si votre organisation effectue l’authentification via Microsoft Entra ID, vous devez désactiver l’authentification locale (authentification avec des clés) afin que les utilisateurs de l’organisation utilisent toujours Microsoft Entra ID.

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

La première étape consiste à créer un sous-domaine personnalisé. Si vous voulez utiliser une ressource Azure AI services existante n’ayant pas de nom de sous-domaine personnalisé, suivez les instructions de la rubrique Sous-domaines personnalisés d’Azure AI services pour activer un sous-domaine personnalisé pour votre ressource.

Commencez par ouvrir Azure Cloud Shell. Ensuite, sélectionnez un abonnement :
```
Set-AzContext -SubscriptionName <SubscriptionName>
```
Ensuite, créez une ressource Azure AI services 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>
```
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.

Notes

Gardez à l’esprit que la propagation des attributions de rôles Azure peut prendre cinq minutes.

Inscrivons d’abord une application dans 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.

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.
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.

Notes

L’ObjectId du principal du service est utilisé, et non pas l’ObjectId de l’application. ACCOUNT_ID est l’ID de ressource Azure du compte Azure AI services que vous avez créé. Cet ID est indiqué dans les « 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 Vision par ordinateur.

Obtenez votre TenantId :

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

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 KeyVault.

Appelez l’API Vision par ordinateur :

$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

Azure AI services prend en charge l’authentification Microsoft Entra avec des identités managées pour les ressources Azure. Les identités managées pour les ressources Azure peuvent autoriser l’accès aux ressources des services Azure AI à l’aide des informations d’identification Microsoft Entra à partir d’applications exécutées sur des machines virtuelles (VM) Azure, des applications de fonction, des groupes de machines virtuelles identiques 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 les identités managées pour les ressources Azure en vue d’autoriser les ressources Azure AI services depuis 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 ressources Azure, consultez :

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 Azure AI services. 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.

Authentifier les requêtes auprès d’Azure AI services

Prérequis

En-têtes d’authentification

Authentifier avec une clé de ressource monoservice

Authentifier avec une clé de ressource multiservice

Régions prises en charge

Exemples de demandes

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

Exemples de demandes

S’authentifier avec Microsoft Entra ID

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

Attribuer un rôle à un principal de service

Exemple de requête

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

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

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

Voir aussi

Ressources supplémentaires