Se connecter à la Recherche Azure AI à l’aide de l’authentification de clé

Article
03/13/2024

Recherche Azure AI offre une authentification basée sur des clés que vous pouvez utiliser pour les connexions à votre service de recherche. Une clé API est une chaîne unique composée de 52 nombres et lettres générés de manière aléatoire. Une requête faite à un point de terminaison du service de recherche est acceptée si la requête et la clé API sont toutes deux valides.

Remarque

Une petite remarque sur l’utilisation de la terminologie « clé » dans Recherche Azure AI. Une « clé API », décrite dans cet article, fait référence à un GUID utilisé pour l’authentification d’une requête. Un terme distinct, « clé de document », fait référence à une chaîne unique dans votre contenu indexé utilisé pour identifier de manière unique des documents dans un index de recherche.

Types de clés API

Il existe deux types de clés utilisées pour l’authentification d’une requête :

Type	Niveau d’autorisation	Maximum	Création
Administrateur	Accès complet (lecture-écriture) pour toutes les opérations de contenu	2 ¹	Deux clés d’administration, appelées clés principale et secondaire dans le portail, sont générées quand le service est créé et peuvent être régénérées individuellement à la demande.
Requête	Accès en lecture seule, délimité à la collection de documents d’un index de recherche	50	Une clé de requête est générée avec le service. Vous pouvez en créer davantage à la demande grâce à un administrateur de service de recherche.

¹ La possession de deux clés permet de substituer une clé quand l’autre est utilisée pour un accès continu au service.

Visuellement, il n’existe aucune distinction entre une clé d’administration et une clé de requête. Les deux clés sont des chaînes composées de 52 caractères alphanumériques générés de façon aléatoire. Si vous n’êtes pas sûr du type de clé spécifié dans votre application, vous pouvez vérifier les valeurs de clé dans le portail.

Utiliser des clés API sur les connexions

Les clés API sont utilisées pour les requêtes de plan de données (contenu), telles que la création ou l’accès à un index ou toute autre requête représentée dans les API REST Recherche. Lors de la création du service, une clé API est le seul mécanisme d’authentification pour les opérations de plan de données, mais vous pouvez remplacer ou compléter l’authentification par clé avec des rôles Azure si vous ne pouvez pas utiliser de clés codées en dur dans votre code.

Les clés API sont spécifiées dans les requêtes clientes à un service de recherche. La transmission d’une clé API valide à la demande est considérée comme preuve que la demande provient d’un client autorisé. Si vous créez, modifiez ou supprimez des objets, vous avez besoin d’une clé API d’administration. Sinon, les clés de requête sont généralement distribuées aux applications clientes qui émettent des requêtes.

Vous pouvez spécifier des clés API dans un en-tête de demande pour les appels d’API REST ou dans le code qui appelle les bibliothèques clientes azure.search.documents dans les kits de développement logiciel (SDK) Azure. Si vous utilisez le portail Microsoft Azure pour effectuer des tâches, votre attribution de rôle détermine le niveau d’accès.

Les meilleures pratiques pour l’utilisation de clés codées en dur dans les fichiers sources sont les suivantes :

Utilisez uniquement des clés API si la divulgation des données ne présente pas de risque (par exemple, lorsque vous utilisez des échantillons de données) et si vous travaillez derrière un pare-feu. L’exposition des clés API représente un risque pour les données et pour l’utilisation non autorisée de votre service de recherche.
Vérifiez toujours le code, les échantillons et les documents de formation avant de les publier pour vous assurer que vous n’avez pas oublié de clés API valides.
Pour les charges de travail de production, passez à Microsoft Entra ID avec accès en fonction du rôle. Ou, si vous souhaitez continuer à utiliser des clés API, veillez à toujours surveiller qui a accès à vos clés API et à régénérer les clés API régulièrement.

Utilisation des clés API dans le portail Azure :

L’authentification par clé est intégrée. Par défaut, le portail essaie d’abord les clés API. Toutefois, si vous désactivez les clés API et configurez des attributions de rôles, le portail utilise plutôt des attributions de rôles.

Utilisation des clés API dans PowerShell :

Définissez des clés API dans l’en-tête de demande en utilisant la syntaxe suivante :

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Vous trouverez un exemple de script montrant l’utilisation des clés API pour différentes opérations dans Démarrage rapide : créer un index Recherche Azure AI dans PowerShell à l’aide d’API REST.

Utilisation des clés API dans les appels REST :

Définissez une clé d’administration dans l’en-tête de la requête. Vous ne pouvez pas passer de clés d’administration sur l’URI ou dans le corps de la requête.

Les clés d’administration sont utilisées pour les opérations de création-lecture-mise à jour-suppression et sur les requêtes émises au service de recherche lui-même, telles que l’établissement d’une liste d’objets ou la demande de statistiques sur le service.

Les clés de requête sont utilisées pour les opérations de recherche ou de suggestion qui ciblent la collection index/docs. Pour POST, définissez api-key dans l’en-tête de demande. Ou placez la clé sur l’URI pour un GET : GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]

Remarque

L’insertion de données sensibles comme une api-key dans l’URI de requête est considérée comme une pratique peu sécurisée. Pour cette raison, Recherche Azure AI accepte uniquement une clé de requête en tant que api-key dans la chaîne de requête. En règle générale, nous vous recommandons de transmettre votre api-key en tant qu'en-tête de demande.

Autorisations d’affichage ou de gestion des clés API

Les autorisations d’affichage et de gestion des clés API sont transmises via des attributions de rôles. Les membres ayant les rôles suivants peuvent afficher et régénérer les clés :

Propriétaire
Contributeur
Contributeur du service de recherche
Administrateur et coadministrateur (classique)

Les rôles suivants n’ont pas accès aux clés API :

Lecteur
Contributeur de données d’index de la Recherche
Lecteur de données d’index de la Recherche

Rechercher des clés existantes

Vous pouvez consulter et gérer les clés API dans le portail Azure ou via PowerShell, Azure CLI ou l’API REST.

Connectez-vous au Portail Azure, puis trouvez votre service de recherche.
Sous Paramètres, sélectionnez Clés pour afficher les clés d’administration et de requête.

Installez le module Az.Search :
```
Install-Module Az.Search
```

Retourner des clés d’administration :

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Retourner des clés de requête :

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Utilisez les commandes suivantes pour retourner les clés API d’administration et de requête, respectivement :

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Utilisez Liste des clés d’administration ou Liste des clés de requête dans l’API REST de gestion pour retourner des clés API.

Vous devez disposer d’une attribution de rôle valide pour retourner ou mettre à jour les clés API. Consultez Gérer votre service Recherche Azure AI avec des API REST pour obtenir des conseils sur le respect des exigences en matière de rôle à l’aide des API REST.

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

Créer des clés de requête

Les clés de requête sont utilisées pour l'accès en lecture seule aux documents au sein d'un index pour les opérations ciblant une collection de documents. Les requêtes de recherche, de filtrage et de suggestion sont toutes des opérations qui utilisent une clé de requête. Toute opération en lecture seule qui renvoie des données système ou des définitions d'objet, comme une définition d'index ou un statut d'indexation, nécessite une clé d'administration.

Il est essentiel de restreindre l'accès et les opérations dans les applications clientes afin de protéger les ressources de recherche de votre service. Utilisez toujours une clé de requête plutôt qu'une clé d'administration pour toutes les requêtes provenant d'une application cliente.

Connectez-vous au Portail Azure, puis trouvez votre service de recherche.
Sous Paramètres, sélectionnez Clés pour afficher les clés API.
Sous Gérer les clés de requête, utilisez la clé de requête déjà générée pour votre service, ou créez des clés de requête. La clé de requête par défaut n'est pas nommée, mais les autres clés de requête générées peuvent être nommées pour faciliter la gestion.

Utilisez Créer des clés de requête dans l’API REST de gestion.

Vous devez disposer d’une attribution de rôle valide pour créer ou gérer des clés API. Consultez Gérer votre service Recherche Azure AI avec des API REST pour obtenir des conseils sur le respect des exigences en matière de rôle à l’aide des API REST.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

Régénération des clés d’administration

Deux clés d'administration sont créées pour chaque service. Vous pouvez ainsi remplacer la clé primaire tout en utilisant la clé secondaire pour assurer la continuité de vos activités.

Sous Paramètres, sélectionnez Clés, puis copiez la clé secondaire.
Pour toutes les applications, mettez à jour les paramètres de la clé API afin d’utiliser la clé secondaire.
Régénérez la clé principale.
Mettez à jour toutes les applications pour qu’elles utilisent la nouvelle clé principale.

Si, par inadvertance, vous régénérez les deux clés en même temps, toutes les requêtes de client utilisant ces clés échoueront (HTTP 403 Refusé). Toutefois, le contenu n’est pas supprimé et vous ne subissez pas de verrouillage permanent.

Vous pouvez toujours accéder au service via le portail ou par programme. Les fonctions de gestion reposent sur un ID d’abonnement et non sur une clé API de service. Elles restent donc disponibles, même si vos clés API ne le sont pas.

Après avoir créé des clés via le portail ou la couche de gestion, l’accès à votre contenu (index, indexeurs, sources de données, cartes de synonymes) est restauré dès que vous fournissez ces clés sur les requêtes.

Sécuriser les clés API

Utilisez des attributions de rôles pour restreindre l’accès aux clés API.

Notez qu’il n’est pas possible d’utiliser le chiffrement de clé gérée par le client pour chiffrer les clés API. Seules les données sensibles dans le service de recherche lui-même (par exemple, le contenu d’index ou les chaînes de connexion dans les définitions d’objets de source de données) peuvent être chiffrées par CMK.

Accédez à la page du service de recherche dans le portail Azure.
Dans le volet de navigation de gauche, sélectionnez Contrôle d’accès (IAM), puis l’onglet Attributions de rôles.
Dans le filtre Rôle, sélectionnez les rôles autorisés à afficher ou à gérer les clés (Propriétaire, Contributeur, Contributeur du service de recherche). Les principaux de sécurité qui en résultent et qui sont affectés à ces rôles disposent d’autorisations clés sur votre service de recherche.
Par précaution, vérifiez également l’onglet Administrateurs classiques pour déterminer si les administrateurs et les coadministrateurs ont accès.