Se connecter à Recherche Azure AI à l’aide de rôles

Remarque

Recherche Azure AI est disponible via le portail Azure, les API REST et les SDK Azure. Il sous-tend également Foundry IQ, la couche de connaissances managée qui transforme le contenu d’entreprise en bases de connaissances réutilisables et prenant en charge les autorisations pour les agents dans le portail Microsoft Foundry.

Recherche Azure AI prend en charge le contrôle d’accès basé sur les rôles via Microsoft Entra ID. 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.

Si vous attribuez plusieurs rôles à un principal de sécurité, les autorisations sont combinées. Les attributions de rôles s’appliquent à tous les outils et bibliothèques clientes.

Cet article explique comment attribuer des rôles intégrés pour l'administration de services, le développement, ainsi que l'accès en lecture seule aux requêtes et à la récupération des données. Il fournit également des étapes pour créer des rôles personnalisés et tester des attributions de rôles.

Conseil / Astuce

Prérequis

Rôles intégrés

Les rôles sont une collection d’autorisations qui affectent le plan de contrôle ou le plan de données :

  • Plan de contrôle : Opérations pour l’approvisionnement, la configuration et l’administration du service. Les opérations de plan de contrôle incluent la création ou la suppression de services de recherche, la liste des clés API et la gestion des paramètres réseau et d’authentification. Disponible via les API REST Azure Resource Manager, Search Management REST API et les bibliothèques clientes Kit de développement logiciel (SDK) Azure équivalentes.

  • Plan de données : Opérations sur le point de terminaison du service de recherche. Les opérations de plan de données se répartissent en deux catégories : la gestion des objets et l’accès au contenu. Disponible via les API REST Search Service et les bibliothèques clientes Kit de développement logiciel (SDK) Azure équivalentes.

Descriptions des rôles

Les rôles intégrés suivants accordent des autorisations à Recherche Azure AI. Les rôles de plan de contrôle sont toujours disponibles, tandis que les rôles de plan de données nécessitent l’activation de l’accès en fonction du rôle sur votre service de recherche. Vous pouvez combiner des rôles intégrés pour un accès plus large ou créer un rôle personnalisé avec les autorisations spécifiques dont vous avez besoin.

Role Avion Descriptif
Propriétaire Contrôle
  • Accès au plan de contrôle total, y compris la possibilité d’attribuer des rôles et de modifier les paramètres d’authentification.
  • Les administrateurs d’abonnement ont ce rôle par défaut.
  • Peut gérer les clés API.
  • Impossible de créer des objets de recherche, de charger des documents, d’index de requête ou de récupérer à partir de bases de connaissances.
Contributeur Contrôle
  • Même niveau d’accès au plan de contrôle que propriétaire, moins la possibilité d’attribuer des rôles.
Lecteur Contrôle
  • Accès au plan de contrôle en lecture seule.
  • Peut afficher les métriques de service et les définitions d’objets.
  • Impossible d’afficher ou de gérer des clés API, charger des documents, interroger des index ou récupérer à partir de bases de connaissances.
Contributeur du service de recherche Contrôle et données
  • Accès total au plan de contrôle. L’accès au plan de données est limité à la gestion des objets.
  • Peut créer des index, des indexeurs, des ensembles de compétences, des bases de connaissances et d’autres objets de recherche.
  • Peut récupérer des clés API d’administration et de requête via des opérations du plan de contrôle.
  • Impossible de charger des documents, des index de requête ou de récupérer directement à partir de bases de connaissances via l’accès en fonction du rôle.
  • Pour obtenir la liste complète des autorisations, consultez Microsoft.Search/searchServices/*.
Contributeur de données d’index de la Recherche Données
  • Accès en lecture-écriture au contenu.
  • Peut charger des documents, interroger des index et récupérer à partir de bases de connaissances.
  • Impossible de modifier les définitions d’objets ou de récupérer des clés d’administration.
Lecteur de données d’index de la Recherche Données
  • Accès au contenu en lecture seule.
  • Peut interroger des index et récupérer à partir de bases de connaissances.
  • Impossible de charger des documents, de modifier des définitions d’objets ou de récupérer des clés d’administration.

Important

  • Le propriétaire, le contributeur et le contributeur de service de recherche peuvent récupérer des clés d’administration, qui fournissent un accès en lecture-écriture complet au plan de données. Accordez uniquement ces rôles aux utilisateurs approuvés.
  • Par défaut, les rôles de plan de données s’appliquent à tous les index du service de recherche. Pour affecter le rôle de contributeur ou de lecteur de données d’index de recherche à un seul index, consultez Accorder l’accès à un seul index.

Résumé des autorisations

Utilisez le tableau suivant pour rechercher rapidement quel rôle fournit les autorisations dont vous avez besoin.

Autorisations Propriétaire/Contributeur Lecteur Contributeur du service de recherche Contributeur de données d’index de recherche Lecteur de données d’index de recherche
Créer et configurer des services Recherche Azure AI ✅ ❌ ✅ ❌ ❌
Accéder au service dans le portail Azure ✅ ✅ ✅ ❌ ❌
Afficher les propriétés du service, les métriques et le point de terminaison ✅ ✅ ✅ ❌ ❌
Répertorier tous les objets sur le service ✅ ✅ ✅ ❌ ❌
Quotas d’accès et statistiques de service ✅ ❌ ✅ ❌ ❌
Afficher, copier et régénérer des clés ✅ ❌ ✅ ❌ ❌
Définir des options d’authentification ✅ ❌ ✅ ❌ ❌
Afficher les rôles, les stratégies et les définitions ✅ ✅ ✅ ❌ ❌
Configurer la sécurité réseau et les connexions privées ✅ ❌ ✅ ❌ ❌
Créer, exécuter et gérer des objets de recherche 1 ❌ ❌ ✅ ❌ ❌
Charger des données pour l’indexation 2 ❌ ❌ ❌ ✅ ❌
Interroger un index ❌ ❌ ❌ ✅ ✅
Récupérer à partir d’une base de connaissances ❌ ❌ ❌ ✅ ✅
Contourner les filtres d’autorisation avec lecture étendue (préversion) ❌ ❌ ❌ ✅ ❌

1 Inclut des index, des indexeurs, des sources de données, des ensembles de compétences, des alias, des mappages de synonymes, des sessions de débogage, des bases de connaissances et des sources de connaissances. Les indexeurs prennent également en charge les opérations d’exécution et de réinitialisation.

2 Un propriétaire ou contributeur peut exécuter l’Assistant Importation de données pour créer et charger des index, même s’ils ne peuvent pas charger de documents dans d’autres clients. De même, les indexeurs peuvent écrire dans n’importe quel index sur le service de recherche, quelles que soient les attributions de rôle par index. Dans les deux cas, le service de recherche (et non l’utilisateur) effectue les actions du plan de données à l’aide de ses autorisations Microsoft.Search/searchServices/indexes/documents/*.

Attribuer des rôles intégrés

Dans cette section, vous attribuez des rôles pour :

Attribuer des rôles pour l’administration de services

Les rôles suivants vous permettent de créer, configurer et gérer un service de recherche. Ces rôles sont hiérarchiques. Sélectionnez-en un en fonction du niveau d’accès dont vous avez besoin.

Role id
Propriétaire 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributeur b24988ac-6180-42a0-ab88-20f7382dd24c
Lecteur acdd72a7-3385-48ef-bd42-f606fba81ae7

  1. Accédez à votre service de recherche dans le portail Azure.

  2. Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .

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

    Capture d’écran de la page Contrôle d’accès (IAM) pour l’attribution de rôles d’administration de service.

  4. Sélectionnez un rôle : Propriétaire, Contributeur ou Lecteur.

  5. Sous l’onglet Members, sélectionnez l’identité d’utilisateur ou de groupe Microsoft Entra. Si vous configurez des autorisations pour un autre service Azure, sélectionnez une identité managée affectée par le système ou affectée par l'utilisateur.

  6. 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 rôles suivants vous permettent de créer des objets de recherche, de charger des documents, d’interroger des index et de récupérer à partir de bases de connaissances. Attribuez les trois rôles pour couvrir l’ensemble des tâches de développement.

Role id
Contributeur du service de recherche 7ca78c08-252a-4471-8644-bb5ff32d4ba0
Contributeur de données d’index de la Recherche 8ebe5a00-799e-43f5-93ac-243d3dce84a7
Lecteur de données d’index de la Recherche 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Accédez à votre service de recherche dans le portail Azure.

  2. Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .

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

    Capture d’écran de la page Contrôle d’accès (IAM) pour l’attribution de rôles de développement.

  4. Sélectionnez Contributeur de service de recherche.

  5. Sous l’onglet Members, sélectionnez l’identité d’utilisateur ou de groupe Microsoft Entra. Si vous configurez des autorisations pour un autre service Azure, sélectionnez une identité managée affectée par le système ou affectée par l'utilisateur.

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

  7. Répétez ces étapes pour affecter le contributeur de données d’index de recherche et le lecteur de données d’index de recherche.

Attribuer des rôles pour l’accès en lecture seule

Utilisez le rôle suivant pour les applications et les processus qui ont uniquement besoin d’un accès en lecture aux index et aux bases de connaissances. Les opérations prises en charge incluent la recherche, la consultation, la saisie semi-automatique et les suggestions pour les index et la récupération pour les bases de connaissances.

Role id
Lecteur de données d’index de la Recherche 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Accédez à votre service de recherche dans le portail Azure.

  2. Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .

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

    Capture d’écran de la page Contrôle d’accès (IAM) pour l’attribution de rôles d’accès aux données en lecture seule.

  4. Sélectionnez le rôle Lecteur de données de l’index de recherche .

  5. Sous l’onglet Members, sélectionnez l’identité d’utilisateur ou de groupe Microsoft Entra. Si vous configurez des autorisations pour un autre service Azure, sélectionnez une identité managée affectée par le système ou affectée par l'utilisateur.

  6. 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 cumulatifs. Vous ne pouvez pas supprimer ou refuser, au niveau de la ressource (service de recherche), des rôles hérités dont l’étendue est définie au niveau de l’abonnement ou du groupe de ressources.

Avant de continuer, configurez votre application pour les connexions sans clé et disposez d’attributions de rôles en place.

  1. Accédez à votre service de recherche dans le portail Azure.

  2. Dans le volet gauche, sélectionnezIndex> pour tester les autorisations liées à l’index :

    • Les contributeurs de service de recherche peuvent créer, modifier et supprimer des objets de recherche, mais ne peuvent pas charger de documents ni exécuter des requêtes. Pour vérifier les autorisations, créez un index de recherche.

    • Les Contributeurs de données d’index de recherche peuvent charger des documents. Il n'existe aucune option de chargement de documents dans le portail Azure en dehors de l'assistant Importer des données, mais vous pouvez reset et exécuter un indexeur pour confirmer les autorisations de chargement des documents.

    • Les lecteurs de données d’index de recherche peuvent interroger des index. Pour vérifier les autorisations, utilisez l’Explorateur de recherche. Vous devez être en mesure d’envoyer des requêtes et d’afficher les résultats, mais vous ne devez pas être en mesure d’afficher les définitions d’index ou de créer des index.

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.

Actuellement, le portail Azure ne prend pas en charge les attributions de rôles au niveau de l'index. Utilisez les Azure CLI, PowerShell ou l’API REST pour attribuer des rôles délimités à un seul index.

Portée par index et opérations de l'indexeur

Les attributions de rôles par index s’appliquent uniquement aux opérations d’API directes, telles que les requêtes ou les chargements de documents à partir d’utilisateurs ou d’applications. Les indexeurs ne sont pas limités par les autorisations par index, car ils fonctionnent avec des informations d’identification au niveau du service.

Un utilisateur disposant du rôle Contributeur de service de recherche peut créer des indexeurs qui écrivent dans n’importe quel index sur le service de recherche, même des index où cet utilisateur n’a pas d’attribution de rôle par index.

Pour une isolation stricte des données entre les index, tenez compte des approches suivantes :

  • Utilisez des services de recherche distincts pour les équipes ou les utilisateurs qui nécessitent une isolation au niveau de l’index.
  • Attribuez un contributeur de service de recherche uniquement aux administrateurs qui gèrent les indexeurs.
  • Utilisez le contrôle d’accès au niveau du document avec des filtres de sécurité pour restreindre les résultats de requête dans un index partagé.

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 dont vous avez besoin.

Les exemples suivants clonent le lecteur de données de l’index de recherche , puis ajoutent 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.

  1. Connectez-vous au portail Azure et accédez à votre service de recherche.

  2. Dans le volet gauche, sélectionnez Contrôle d’accès (IAM) .

  3. Sous l’onglet Rôles, recherchez Search Index Data Reader ou un autre rôle, sélectionnez l'ellipse (...), puis sélectionnez Cloner.

  4. Sous l’onglet Basics, entrez un nom pour le rôle personnalisé, tel que « Search Index Data Explorer », puis sélectionnez Next.

  5. Sous l’onglet Autorisations , sélectionnez Ajouter des autorisations.

  6. Dans le volet Add autorisations, sélectionnez la vignette Recherche Microsoft.

  7. Avec les actions sélectionnées en haut, définissez les autorisations suivantes :

    • Sous Microsoft.Search/operations, sélectionnez Read : répertorier toutes les opérations disponibles.
    • Sous Microsoft.Search/searchServices/indexes, sélectionnez Read : Lire l’index.

  8. Basculez vers Data Actions en haut, puis, sous Microsoft.Search/searchServices/indexes/documents, sélectionnez Read : Lire des documents.

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

    {
    "properties": {
        "roleName": "Search Index Data Explorer",
        "description": "List all indexes on the service and query them.",
        "assignableScopes": [
            "/subscriptions/<subscription>/resourceGroups/<resource-group>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
    }
}

  9. Sélectionnez Ajouter pour fermer le volet.

  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. Pour plus d’informations sur ces étapes, consultez Créer ou mettre à jour les rôles personnalisés Azure à l’aide du portail Azure.

Créer une stratégie d’accès conditionnel

Si vous devez appliquer des stratégies organisationnelles, telles que l’authentification multifacteur, utilisez Accès conditionnel Microsoft Entra.

Pour créer une stratégie d’accès conditionnel pour Recherche Azure AI :

  1. Connectez-vous au portail Azure.

  2. Recherchez Accès conditionnel Microsoft Entra.

  3. Dans la page Vue d’ensemble , sélectionnez Créer une stratégie.

  4. Sous Applications ou actionsCloud, ajoutez Recherche Azure AI en tant qu’application cloud, selon la façon dont vous souhaitez configurer votre stratégie.

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

  6. Enregistrez la stratégie.

Important

Si votre service de recherche a une identité managée qui lui est affectée, le service de recherche spécifique apparaît sous la forme d’une application cloud. Toutefois, la sélection de ce service de recherche spécifique ne met pas en œuvre la politique. Sélectionnez plutôt l’application cloud Recherche Azure AI générale pour appliquer des stratégies d’accès conditionnel à votre service de recherche.

Résolution des problèmes

Lorsque vous développez des applications qui utilisent le contrôle d’accès en fonction du rôle pour l’authentification, vous pouvez rencontrer des problèmes courants :

  • La configuration par défaut d’un service de recherche est une authentification par clé. Si vous ne modifiez pas ce paramètre à la fois en contrôle d'accès en fonction des rôles ou contrôle d'accès basé sur les rôles, toutes les requêtes qui utilisent l'authentification basée sur les rôles sont automatiquement refusées, indépendamment des autorisations sous-jacentes.

  • Si votre requête inclut une clé API avec des informations d’identification basées sur des rôles, le service s’authentifie à l’aide de la clé. Supprimez la clé API de vos en-têtes de requête pour utiliser l’authentification basée sur les rôles.

  • Si le jeton d’autorisation provient d’une identité managée et que vous avez récemment affecté les autorisations appropriées, plusieurs heures peuvent être nécessaires pour que les affectations d’autorisations prennent effet.

  • Si les requêtes avec des autorisations au niveau du document ne retournent pas de résultats attendus, utilisez le contributeur de données d’index de recherche ou créez un rôle personnalisé avec des autorisations élevées (préversion) pour examiner.

Étape suivante

Cet article explique comment attribuer des rôles pour les opérations de contrôle et de plan de données sur Recherche Azure AI. Pour obtenir des instructions complètes sur l’ajout d’un accès en fonction du rôle à votre code d’application :

Connectez votre application à Recherche Azure AI à l’aide d’identités

  • Last updated on