Se connecter à Recherche Azure AI en utilisant des clés

Article
10/16/2024

Recherche Azure AI offre une authentification basée sur des clés 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. Dans votre code source, vous pouvez la spécifier en tant que variable d’environnement ou en tant que paramètre d’application dans votre projet, puis référencer la variable dans la requête. 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.

L’authentification basée sur une clé est la valeur par défaut.

Vous pouvez la remplacer par un accès en fonction du rôle, ce qui élimine la nécessité de recourir à clés codées en dur dans votre codebase.

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 d’administration sont utilisées pour créer, modifier ou supprimer des objets. Les clés d’administration sont également utilisées pour obtenir des définitions d’objets et des informations système.

Les clés de requête sont généralement distribuées aux applications clientes qui émettent des requêtes.

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 pour les requêtes transmises au service de recherche lui-même, telles qu’un listing d’index ou l’obtention de statistiques sur le service.

Voici un exemple d’utilisation de la clé API d’administration sur une requête de création d’index :

### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

Définissez une clé de requête dans un en-tête de requête pour publication ou sur l’URI pour obtenir des informations. Les clés de requête sont utilisées pour les opérations qui ciblent la index/docscollection : Recherche de documents , Autocomplétion, Suggestion ouObtention d’un document .

Voici un exemple d’utilisation de clé API de requête sur une requête GET (Search Documents) :

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2024-07-01&api-key={{queryApiKey}}

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.

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.

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és gérées 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.

Bonnes pratiques

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.

Partager via