Partager via

Se connecter à la Recherche Azure AI en utilisant des rôles

  • Article

Azure fournit un système global d’autorisation basée sur les rôles et d’authentification pour tous les services exécutés sur la plateforme. Dans la recherche Azure AI, vous pouvez attribuer des rôles Azure pour :

L’accès par utilisateur aux résultats de la recherche (parfois appelé sécurité au niveau des lignes ou sécurité au niveau du document) n’est pas pris en charge avec l’attribution de rôle. En guise de solution de contournement, créez des filtres de sécurité qui ajustent les résultats par identité utilisateur, en supprimant les documents auxquels le demandeur ne doit pas avoir accès. Consultez cet exemple de conversation d’entreprise avec RAG pour une démonstration.

Les attributions de rôles sont cumulatives et généralisées pour tous les outils et bibliothèques de client. Vous pouvez attribuer des rôles à l’aide de l’une des approches prises en charge décrites dans la documentation sur le contrôle d’accès basé sur les rôles d’Azure.

L’accès en fonction du rôle est facultatif, mais recommandé. L’alternative est l’authentification par clé, qui est la valeur par défaut.

Prérequis

Les rôles suivants sont intégrés. Si ces rôles sont insuffisants, créez un rôle personnalisé.

Rôle Plane Description
Propriétaire Contrôle et données Accès complet au plan de contrôle de la ressource de recherche, y compris la possibilité d’affecter des rôles Azure. Seul le rôle Propriétaire peut activer ou désactiver les options d’authentification ou gérer des rôles pour d’autres utilisateurs. Les administrateurs d’abonnements sont membres par défaut.

Sur le plan de données, ce rôle a le même accès que le rôle Contributeur de service de recherche. Il inclut l’accès à toutes les actions de plan de données, à l’exception de la possibilité d’interroger les documents d’index.
Contributeur Contrôle et données Même niveau d’accès au plan de contrôle que le Propriétaire, moins la possibilité d’affecter des rôles ou de modifier les options d’authentification.

Sur le plan de données, ce rôle a le même accès que le rôle Contributeur de service de recherche. Il inclut l’accès à toutes les actions de plan de données, à l’exception de la possibilité d’interroger les documents d’index.
Lecteur Contrôle et données L’accès en lecture dans le service entier, ce qui inclut les métriques de recherche, les métriques de contenu (stockage consommé, nombre d’objets) et les définitions d’objet des ressources de plan de données (index, indexeurs, etc.). Toutefois, il ne peut pas lire les clés API ni le contenu dans les index.
Contributeur du service de recherche Contrôle et données Accès en lecture-écriture aux définitions d’objets (index, alias, mappages de synonymes, indexeurs, sources de données et ensembles de compétences). Ce rôle est destiné aux développeurs qui créent des objets et aux administrateurs qui gèrent un service de recherche et ses objets, mais sans accès au contenu de l’index. Utilisez ce rôle pour créer, supprimer et répertorier des index, obtenir des définitions d’index et des informations sur le service (statistiques et quotas), tester des analyseurs, créer et gérer des mappages de synonymes, des indexeurs, des sources de données et des ensembles de compétences. Consultez Microsoft.Search/searchServices/* pour obtenir la liste des autorisations.
Contributeur de données d’index de la Recherche Données Accès en lecture-écriture au contenu dans des index. Ce rôle est destiné aux développeurs ou aux propriétaires d’index qui ont besoin d’importer, d’actualiser ou d’interroger la collection de documents d’un index. Ce rôle ne prend pas en charge la création ou la gestion d’index. Par défaut, ce rôle est destiné à tous les index d’un service de recherche. Pour réduire l’étendue, consultez Accorder l’accès à un seul index.
Lecteur de données d’index de la Recherche Données Accès en lecture seule pour interroger des index de recherche. Ce rôle est destiné aux applications et utilisateurs qui exécutent des requêtes. Ce rôle ne prend pas en charge l’accès en lecture aux définitions d’objets. Par exemple, vous ne pouvez pas lire une définition d’index de recherche ou obtenir des statistiques du service de recherche. Par défaut, ce rôle est destiné à tous les index d’un service de recherche. Pour réduire l’étendue, consultez Accorder l’accès à un seul index.

Combinez ces rôles pour obtenir des autorisations suffisantes pour votre cas d’usage.

Remarque

Si vous désactivez l’accès en fonction du rôle Azure, les rôles intégrés pour le plan de contrôle (Propriétaire, Contributeur, Lecteur) continuent d’être disponibles. La désactivation de l’accès en fonction du rôle supprime uniquement les autorisations liées aux données associées à ces rôles. Si les rôles du plan de données sont désactivés, le contributeur du service de recherche équivaut au contributeur du plan de contrôle.

Attribuer des rôles

Dans cette section, attribuez des rôles pour :

Attribuer des rôles pour l’administration de services

En tant qu’administrateur de services, vous pouvez créer et configurer un service de recherche et effectuer toutes les opérations de plan de contrôle décrites dans l’API REST de gestion ou les bibliothèques clientes équivalentes. Selon le rôle, vous pouvez également effectuer la plupart des tâches de plan de données de l’API REST Search.

  1. Connectez-vous au portail Azure.

  2. Accéder à votre service de recherche.

  3. Sélectionnez Contrôle d’accès (IAM) dans le menu de navigation de gauche.

  4. Sélectionnez + Ajouter>Ajouter une attribution de rôle.

  5. Sélectionnez un rôle applicable :

    • Propriétaire (accès complet à toutes les opérations de plan de données et de plan de contrôle, à l’exception des autorisations de demande)
    • Contributeur (identique à Propriétaire, à l’exception des autorisations d’attribution de rôle)
    • Lecteur (acceptable pour la surveillance et la consultation des métriques)

  6. Sous l’onglet Membres, sélectionnez l’identité de l’utilisateur ou du groupe Microsoft Entra.

  7. Dans l’onglet Passer en revue + affecter, sélectionnez Passer en revue + affecter pour affecter le rôle.

Attribuer des rôles pour le développement

Les attributions de rôle sont globales dans le service de recherche. Pour limiter les autorisations à un seul index, utilisez plutôt PowerShell ou Azure CLI pour créer un rôle personnalisé.

L’association des rôles Contributeur/Propriétaire et Lecteur de données d’index de recherche fournit elle aussi un accès complet.

Important

Si vous configurez l’accès en fonction du rôle pour un service ou un index, et que vous fournissez également une clé API sur la demande, le service de recherche utilise la clé API pour l’authentification.

  1. Connectez-vous au portail Azure.

  2. Accéder à votre service de recherche.

  3. Sélectionnez Contrôle d’accès (IAM) dans le menu de navigation de gauche.

  4. Sélectionnez + Ajouter>Ajouter une attribution de rôle.

    Page Contrôle d’accès (IAM) avec le menu Ajouter une attribution de rôle ouvert.

  5. Sélectionnez un rôle :

    • Contributeur de services de recherche (opérations create-read-update-delete sur les index, les indexeurs, les ensembles de compétences et les autres objets de niveau supérieur)
    • Contributeur de données d’index de recherche (charge des documents et exécute des travaux d’indexation)
    • Lecteur de données d’index de recherche (demande un index)

    L’association des rôles Contributeur/Propriétaire et Lecteur de données d’index de recherche fournit elle aussi un accès complet.

  6. Sous l’onglet Membres, sélectionnez l’identité de l’utilisateur ou du groupe Microsoft Entra.

  7. Dans l’onglet Passer en revue + affecter, sélectionnez Passer en revue + affecter pour affecter le rôle.

  8. Répétez pour les autres rôles. La plupart des développeurs ont besoin des trois rôles.

Attribuer des rôles pour les demandes en lecture seule

Utilisez le rôle Lecteur de données d’index de recherche pour les applications et les processus qui ont uniquement besoin d’un accès en lecture à un index.

Il s’agit d’un rôle très spécifique. Il octroie un accès GET ou POST à la collection de documents d’un index de recherche pour la recherche, l’autocomplétion et les suggestions. Il ne prend pas en charge les opérations GET ou LIST sur un index ou d’autres objets de niveau supérieur, ni les statistiques de service GET.

Cette section fournit les étapes de base pour configurer l’attribution de rôle et est présentée pour des raisons d’exhaustivité. Toutefois, nous vous recommandons de consulter Utiliser la Recherche Azure AI sans clés pour obtenir des instructions complètes sur la configuration de votre application pour l’accès en fonction du rôle.

  1. Connectez-vous au portail Azure.

  2. Accéder à votre service de recherche.

  3. Sélectionnez Contrôle d’accès (IAM) dans le menu de navigation de gauche.

  4. Sélectionnez + Ajouter>Ajouter une attribution de rôle.

  5. Sélectionnez le rôle Lecteur de données d’index de recherche.

  6. Sous l’onglet Membres, sélectionnez l’identité de l’utilisateur ou du groupe Microsoft Entra. Si vous configurez des autorisations pour un autre service, vous utilisez peut-être une identité managée par l’utilisateur ou un système. Choisissez cette option si l’attribution de rôle concerne une identité de service.

  7. Dans l’onglet Passer en revue + affecter, sélectionnez Passer en revue + affecter pour affecter le rôle.

Tester les attributions de rôles

Utilisez un client pour tester les attributions de rôles. N’oubliez pas que les rôles sont des rôles cumulatifs et hérités qui sont délimités au niveau de l’abonnement ou du groupe de ressources et ne peuvent donc pas être supprimés ni refusés au niveau de la ressource (service de recherche).

Configurez votre application pour les connexions sans clé et obtenez les attributions de rôle en place avant le test.

  1. Connectez-vous au portail Azure.

  2. Accéder à votre service de recherche.

  3. Dans la page de la vue d’ensemble, sélectionnez l’onglet Index :

    • Les contributeurs du service de recherche peuvent afficher et créer n’importe quel objet, mais ils ne peuvent pas charger de documents ni interroger un index. Pour vérifier les autorisations, créez un index de recherche.

    • Les Contributeurs de données d’index de recherche peuvent charger des documents. Le portail ne propose aucune option de chargement de documents en dehors de l’assistant Importation de données. Cependant, vous pouvez réinitialiser et exécuter un indexeur pour confirmer les autorisations de chargement de documents.

    • Les personnes avec le rôle Lecteur de données de l’index de recherche peuvent interroger l’index. Pour vérifier les autorisations, utilisez l’Explorateur de recherche. Vous devez pouvoir envoyer des requêtes et afficher les résultats, mais pas consulter la définition d’index.

Tester en tant qu’utilisateur actuel

Si vous êtes déjà contributeur ou propriétaire de votre service de recherche, vous pouvez présenter un jeton de porteur pour votre identité utilisateur pour l’authentification auprès de la recherche Azure AI.

  1. Obtenez un jeton du porteur pour l’utilisateur actuel à l’aide d’Azure CLI :

    az account get-access-token --scope https://search.azure.com/.default

    Ou à l’aide de PowerShell :

    Get-AzAccessToken -ResourceUrl https://search.azure.com

  2. Collez ces variables dans un nouveau fichier texte dans Visual Studio Code.

    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@index-name = PASTE-YOUR-INDEX-NAME-HERE
@token = PASTE-YOUR-TOKEN-HERE

  3. Collez puis envoyez une requête pour vérifier l’accès. En voici une qui interroge l’index hotels-quickstart :

    POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

    {
         "queryType": "simple",
         "search": "motel",
         "filter": "",
         "select": "HotelName,Description,Category,Tags",
         "count": true
     }

Accorder l’accès à un index unique

Dans certains scénarios, il est possible que vous souhaitiez limiter l’accès d’une application à une seule ressource, comme un index.

Le portail ne prend actuellement pas en charge les attributions de rôles à ce niveau de précision, mais vous pouvez le faire avec PowerShell ou Azure CLI.

Dans PowerShell, utilisez New-AzRoleAssignment, en indiquant le nom de l’utilisateur ou du groupe Azure et l’étendue de l’attribution.

  1. Chargez les modules Azure et AzureAD, puis connectez-vous à votre compte Azure :

    Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount

  2. Ajoutez une attribution de rôle étendue à un index individuel :

    New-AzRoleAssignment -ObjectId <objectId> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Créer un rôle personnalisé

Si les rôles intégrés ne fournissent pas la bonne combinaison d’autorisations, vous pouvez créer un rôle personnalisé pour prendre en charge les opérations requises.

Cet exemple clone le lecteur de données d’index de recherche, puis ajoute la possibilité de répertorier les index par nom. Normalement, la liste des index sur un service de recherche est considérée comme un droit administratif.

Ces étapes sont dérivées de Créer ou de mettre à jour des rôles personnalisés Azure à l’aide du Portail Azure. Le clonage à partir d’un rôle existant est pris en charge dans une page de service de recherche.

Ces étapes créent un rôle personnalisé qui augmente les droits de requête de recherche pour inclure des index de liste par nom. En règle générale, la liste des index est considérée comme une fonction d’administrateur.

  1. Dans le portail Azure, accédez à votre service de recherche.

  2. Sélectionnez Contrôle d’accès (IAM) dans le menu de navigation de gauche.

  3. Dans la barre d’action, sélectionnez Rôles.

  4. Cliquez avec le bouton droit sur Lecteur de données d’index de recherche (ou un autre rôle) et sélectionnez Cloner pour ouvrir l’Assistant Créer un rôle personnalisé.

  5. Sous l’onglet Informations de base, indiquez un nom pour le rôle personnalisé, comme "Explorateur de données d’index de recherche", puis sélectionnez Suivant.

  6. Sous l’onglet Autorisations, cliquez sur Ajouter des autorisations.

  7. Sous l’onglet Ajouter des autorisations, recherchez, puis sélectionnez la vignette Recherche Microsoft.

  8. Définissez les autorisations pour votre rôle personnalisé. En haut de la page, à l’aide de la sélection Actions par défaut :

    • Sous Microsoft.Search/operations, sélectionnez Lecture : Répertorier toutes les opérations disponibles.
    • Sous Microsoft.Search/searchServices/index, sélectionnez Lecture : Index de lecture.

  9. Dans la même page, basculez vers Actions de données et sous Microsoft.Search/searchServices/index/documents, sélectionnez Lecture : Lire des documents.

    La définition JSON ressemble à l’exemple qui suit :

    {
 "properties": {
     "roleName": "search index data explorer",
     "description": "",
     "assignableScopes": [
         "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
     ],
     "permissions": [
         {
             "actions": [
                 "Microsoft.Search/operations/read",
                 "Microsoft.Search/searchServices/indexes/read"
             ],
             "notActions": [],
             "dataActions": [
                 "Microsoft.Search/searchServices/indexes/documents/read"
             ],
             "notDataActions": []
         }
     ]
   }
 }

  10. Sélectionnez Vérifier + créer pour créer le rôle. Vous pouvez maintenant affecter des utilisateurs et des groupes au rôle.

Accès conditionnel

Nous recommandons l’accès conditionnel Microsoft Entra si vous devez appliquer des stratégies organisationnelles, notamment l’authentification multifacteur.

Pour activer une stratégie d’accès conditionnel pour Recherche Azure AI, effectuez les étapes suivantes :

  1. Connectez-vous au portail Azure.

  2. Recherchez l’accès conditionnel Microsoft Entra.

  3. Sélectionnez Stratégies.

  4. Sélectionnez Nouvelle stratégie.

  5. Dans la section Applications cloud ou actions de la stratégie, ajoutez Recherche Azure AI en tant qu’application cloud selon la manière dont vous souhaitez configurer votre stratégie.

  6. Mettez à jour les paramètres restants de la stratégie. Par exemple, spécifiez les utilisateurs et les groupes auxquels cette stratégie s’applique.

  7. Enregistrez la stratégie.

Important

Si une identité managée est attribuée à votre service de recherche, celui-ci apparaîtra comme une application cloud qui peut être incluse ou exclue dans le cadre de la stratégie d’accès conditionnel. Les stratégies d’accès conditionnel ne peuvent pas être appliquées à un service de recherche spécifique. Veillez plutôt à sélectionner l’application cloud générale Recherche Azure AI.

Limites

  • Le contrôle d’accès en fonction du rôle peut augmenter la latence de certaines demandes. Chaque combinaison unique de ressource de service (index, indexeur, etc.) et de principal de service déclenche une vérification d’autorisation. Ces vérifications d’autorisation peuvent ajouter jusqu’à 200 millisecondes de latence par demande.

  • Dans de rares cas où les demandes proviennent d’un grand nombre de principaux de service différents, ciblant différentes ressources de service (index, indexeurs, etc.), il est possible que les vérifications d’autorisation entraînent une limitation. La limitation se produit uniquement si des centaines de combinaisons uniques de chaque ressource du service de recherche et du principal de service ont été utilisées en une seconde.

Résolution des problèmes de contrôle d’accès en fonction du rôle

Lorsque vous développez des applications qui utilisent le contrôle d’accès en fonction du rôle pour l’authentification, il est possible que certains problèmes courants se produisent :

  • Si le jeton d’autorisation provient d’une identité managée et que les autorisations appropriées ont été récemment attribuées, il est possible que la prise d’effet de celles-ci prenne plusieurs heures.

  • La configuration par défaut d’un service de recherche est une authentification par clé. Si vous n’avez pas modifié le paramètre de clé par défaut sur Les deux ou Contrôle d’accès en fonction du rôle, toutes les requêtes utilisant l’authentification en fonction du rôle sont automatiquement refusées, quelles que soient les autorisations sous-jacentes.