Application des ACL et du contrôle d’accès en fonction du rôle (RBAC) lors des requêtes dans Recherche Azure AI (préversion)

Le contrôle d’accès au moment de la requête (préversion) garantit que les utilisateurs récupèrent uniquement les résultats de recherche auxquels ils sont autorisés à accéder, en fonction de leur identité, des appartenances à un groupe, des rôles ou des attributs. Cette fonctionnalité est essentielle pour la recherche d’entreprise sécurisée et les flux de travail pilotés par la conformité.

L’accès autorisé dépend des métadonnées d’autorisation ingérées pendant l’indexation. Pour les sources de données d’indexeur qui ont des modèles d’accès intégrés, tels que Azure Data Lake Storage (ADLS) Gen2 et SharePoint dans Microsoft 365, un indexeur peut extraire automatiquement les métadonnées d’autorisation pour chaque document. Pour d’autres sources de données, vous devez assembler vous-même la charge utile du document, et la charge utile doit inclure à la fois le contenu et les métadonnées d’autorisation associées. Vous utilisez ensuite les API Push pour charger l’index.

Cet article explique comment configurer des requêtes qui utilisent des métadonnées d’autorisation pour filtrer les résultats.

Conditions préalables

• Les métadonnées d’autorisation doivent figurer dans les champs de chaîne filterable. Vous n’utiliserez pas le filtre dans vos requêtes, mais le moteur de recherche génère un filtre en interne pour exclure du contenu non autorisé.

• Les métadonnées d’autorisation doivent être constituées d’autorisations de style POSIX qui identifient le niveau d’accès et le groupe ou l’ID d’utilisateur, ou l’ID de ressource du conteneur dans ADLS Gen2 si vous utilisez l’étendue RBAC.

• Pour l’application des ACL lors de l’ingestion personnalisée, stockez userIds et groupIds sous forme d’ID d’objet Microsoft Entra (GUID) dans des champs filtrables. Au moment de la requête, le service compare les identités de x-ms-query-source-authorization aux identifiants stockés. Pour plus d’informations sur le schéma, consultez Indexation des listes de contrôle d’accès aux documents (ACL) à l’aide des API REST Push (préversion).

• Selon la source de données :

  • Pour les sources de données ADLS Gen2, vous devez avoir configuré des listes de contrôle d’accès (ACL) et/ou des rôles de contrôle d’accès basé sur un rôle (RBAC) Azure au niveau du conteneur.
  • Pour Azure sources de données Blob, vous devez disposer d’attributions de rôles sur le conteneur. Vous pouvez utiliser un indexeur intégré, une source de connaissances ou des API Push pour indexer les métadonnées d’autorisation dans votre index.
  • Pour SharePoint sources de données, vous devez configurer des listes de contrôle d’accès (ACL). Vous pouvez utiliser un indexeur intégré SharePoint et le configurer avec des fonctionnalités d’ingestion ACL. Vous pouvez également utiliser une source de connaissances indexée SharePoint et la configurer pour appliquer des autorisations au niveau du document. Les autorisations basées sur des groupes, y compris les groupes Microsoft 365, sont prises en charge lorsqu’elles sont ingérées sous forme d’ID d’objet Entra. L’extension de groupe se produit au moment de la requête via Microsoft Graph.

• Utilisez l’API REST version la plus récente ou un package d’aperçu d’un Kit de développement logiciel (SDK) Azure pour interroger l’index ou la source de connaissances. Cette version de l’API prend en charge les requêtes internes qui filtrent les résultats non autorisés.

Limitations

• Si l'évaluation de la liste de contrôle d'accès échoue (par exemple, si l'API Graph n'est pas disponible), le service retourne 5xx et ne retourne pas un jeu de résultats partiellement filtré.

• La mise à jour des ACL dépend de la méthode d’ingestion. Pour éviter les décisions d’autorisation obsolètes, planifiez la façon dont chaque source propage les modifications d’autorisation vers l’index :

  • Un indexeur SharePoint planifié actualise les modifications d’autorisation au niveau de l’élément sur chaque exécution. Les modifications apportées à une étendue parente (site, bibliothèque, liste ou dossier) héritées par les éléments enfants nécessitent une resynchronisation.
  • Un indexeur ADLS Gen2 nécessite une resynchronisation pour actualiser les listes de contrôle d’accès.
  • L’ingestion personnalisée ou push vous oblige à reingérer les documents affectés.

• La visibilité des documents nécessite les deux :

  • Rôle RBAC de l’application appelante (en-tête d’autorisation).
  • Identité de l’utilisateur transmise par x-ms-query-source-authorization.

• Les requêtes ACL initiales peuvent rencontrer une latence plus élevée par rapport aux requêtes suivantes, en raison de la surcharge de mise en cache et de résolution des autorisations.

• Pour le contenu indexé de SharePoint, un groupe Microsoft Entra imbriqué dans un groupe SharePoint n’est pas étendu. La résolution transitive des groupes Microsoft Entra ne prend pas en charge cette relation mixte. Consultez les relations de groupe prises en charge.

Limites d’entrée de liste de contrôle d’accès par source de données

Les limites d’entrée de liste de contrôle d’accès (ACL) définissent le nombre d’enregistrements d’autorisation distincts pouvant être associés à un fichier, un dossier ou un élément au sein d’une source de données connectée. Chaque entrée représente une identité d’utilisateur ou de groupe unique et les droits d’accès accordés à cette identité (par exemple, Lecture, Écriture ou Exécution).

Le nombre maximal d’entrées ACL prises en charge par Recherche Azure AI fonctionnalité varie en fonction du type de source de données :

Azure Data Lake Storage Gen2 (ADLS Gen2) : chaque fichier ou répertoire peut avoir jusqu’à 32 autorisations DCL. Dans ce contexte, une entrée signifie un principal unique (utilisateur ou groupe) avec un jeu d’autorisations spécifique. Exemple : l’attribution de l'accès en lecture à « Tout le monde » et de l'accès en exécution aux « utilisateurs Azure » compte comme deux entrées de liste de contrôle d'accès.

SharePoint dans Microsoft 365 : La source de données SharePoint dans la recherche prend en charge jusqu’à 1 000 autorisations par fichier. Chaque entrée représente une attribution d’utilisateur ou de groupe unique dans la liste d’autorisations de l’élément. Cela est distinct des limites globales des étendues d’autorisation uniques par liste ou bibliothèque, qui régit le nombre d’éléments pouvant avoir des autorisations uniques.

Ces limites déterminent comment Recherche Azure AI de manière granulaire peuvent respecter les autorisations au niveau de l’élément lors de l’indexation ou du filtrage des résultats de recherche. Si un élément dépasse ces limites d’entrées d’ACL, les permissions au-delà de la limite risquent de ne pas être appliquées lors de la requête.

Fonctionnement de l'application des règles au moment des requêtes.

Cette section répertorie l’ordre des opérations pour l’application de la liste de contrôle d’accès au moment de la requête. Les opérations varient selon que vous utilisez l'étendue Azure RBAC ou les ID de groupe ou d'utilisateur Microsoft Entra ID.

1. Entrée des autorisations utilisateur

L’application de l’utilisateur final inclut un jeton d’accès aux requêtes dans le cadre de la demande de requête de recherche, et ce jeton d’accès est généralement l’identité de l’utilisateur. Le tableau suivant répertorie la source des autorisations utilisateur prises en charge par Recherche Azure AI pour l’application de la liste de contrôle d’accès :

2. Construction du filtre de sécurité

En interne, Recherche Azure AI construit dynamiquement des filtres de sécurité en fonction des autorisations utilisateur fournies. Ces filtres de sécurité sont automatiquement ajoutés à tous les filtres susceptibles d’être fournis avec la requête si l’option de filtre d’autorisation est activée pour l’index.

Pour Azure RBAC, les autorisations sont des listes de chaînes d’ID de ressource. Il doit y avoir une attribution de rôle Azure (Lecteur de données Blob de stockage) sur la source de données qui accorde l’accès au jeton principal de sécurité dans l’en-tête d’autorisation. Le filtre exclut les documents s’il n’existe aucune attribution de rôle pour le principal derrière le jeton d’accès sur la demande.

3. Filtrage des résultats

Le filtre de sécurité correspond efficacement aux userIds, groupIds et rbacScope de la requête à chaque liste des ACL dans chaque document de l’index de recherche pour limiter les résultats renvoyés à ceux auxquels l’utilisateur a accès. Il est important de noter que chaque filtre est appliqué indépendamment et qu’un document est considéré comme autorisé si un filtre réussit. Par exemple, si un utilisateur a accès à un document via userIds, mais pas par groupIds, le document est toujours considéré comme valide et retourné à l’utilisateur.

groupes SharePoint au moment de la requête

À partir de l’API REST 2026-05-01-preview, Recherche Azure AI peut prendre en compte les appartenances aux groupes de sites SharePoint, tels que Propriétaires, Membres, Visiteurs et les groupes de sites personnalisés, lors de l’exécution de la requête. Pour activer ce scénario, l’index doit inclure :

• Propriété sharePointConnectorAppRegistration qui fait référence aux informations d’identification d’identité fédérée de l’application Microsoft Entra utilisée pour appeler SharePoint au nom de l’utilisateur.
• Champ marqué avec l’attribut sharepointSiteUrl: true qui stocke l’URL du site SharePoint pour chaque élément indexé (généralement nommé SharePointSiteUrl et rempli à partir du champ source metadata_spo_site_url).

Au moment de la requête, Recherche Azure AI utilise l’application inscrite et l’URL du site sur chaque document candidat pour résoudre les appartenances groupe SharePoint de l’utilisateur appelant sur ce site. Les groupes résolus sont comparés aux valeurs préfixées par spg: stockées dans le champ de filtre des autorisations groupIds. Le préfixe spg: distingue les groupes de sites SharePoint des identifiants d’objet de groupe Microsoft Entra, qui sont stockés sans préfixe.

Pour plus d’informations sur la configuration et les limitations, consultez Configurer la prise en charge des groupes SharePoint.

Si SharePoint filtrage d’autorisations retourne des résultats manquants ou inattendus, consultez Résoudre les problèmes SharePoint filtrage des autorisations.

Exemple : Requête avec application du groupe de sites SharePoint

La requête est identique à la requête standard soumise aux ACL. Le service de recherche utilise le sharePointConnectorAppRegistration de l’index pour résoudre l’appartenance au groupe SharePoint pour le compte de l’appelant. Incluez GroupIds dans la clause select pour voir les valeurs préfixées par spg: dans la réponse.

POST {{endpoint}}/indexes/{index}/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,SharePointSiteUrl,GroupIds",
    "orderby": "name asc"
}

Exemple de requête

Voici un exemple de requête à partir d'un exemple de code. Le jeton de requête est un jeton d’accès Microsoft Entra pour l’utilisateur interrogeant.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

Autorisations élevées pour analyser les résultats incorrects (version préliminaire)

Le débogage de requêtes qui incluent des métadonnées d’autorisation peut poser problème, car les résultats de la recherche sont spécifiques à chaque utilisateur. En tant que développeur ou administrateur, vous devrez peut-être disposer d’autorisations élevées pour retourner les résultats, quelles que soient les métadonnées d’autorisation afin de pouvoir examiner les problèmes liés aux requêtes retournant du contenu non autorisé.

Pour examiner, vous devez être en mesure de :

• Affichez l’ensemble de documents que l’utilisateur final est en mesure d’afficher en fonction des autorisations de cet utilisateur.

• Affichez tous les documents dans l’index pour examiner pourquoi certains peuvent ne pas être visibles par l’utilisateur final.

Vous pouvez effectuer ces tâches en ajoutant un en-tête personnalisé, x-ms-enable-elevated-read: trueà une requête.

Autorisations pour les demandes de lecture élevées

Vous devez disposer d’autorisations Contributeur aux données d’index de recherche ou d’un rôle personnalisé qui inclut l'autorisation Lecture Elever.

Les requêtes sont une opération de plan de données. Par conséquent, le rôle personnalisé ne peut se composer que d’autorisations de plan de données atomiques. Pour un rôle personnalisé, ajoutez l’autorisation Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read.

Ajouter un en-tête de lecture prioritaire à une requête

Après avoir configuré des autorisations, vous pouvez exécuter la requête. L’exemple suivant est une requête dans un index de recherche.

POST {endpoint}/indexes('{indexName}')/search.post.search?api-version=2026-08-01-preview
Authorization: Bearer {AUTH_TOKEN}
x-ms-query-source-authorization: {TOKEN}
x-ms-enable-elevated-read: true

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

Modification importante du comportement des fonctionnalités de liste de contrôle d’accès dans des versions d’API en préversion spécifiques

Avant la version 2025-11-01-preview de l’API REST, les versions préliminaires antérieures 2025-05-01-preview et 2025-08-01-preview retournaient tous les documents lors de l’utilisation d’une clé API du service ou lorsqu'on utilise des rôles Entra autorisés, même si aucun jeton utilisateur n’a été fourni. Les applications qui n’ont pas validé la présence d’un jeton utilisateur peuvent exposer par inadvertance les résultats aux utilisateurs finaux s’ils ne sont pas implémentés correctement ou en suivant les meilleures pratiques.

À compter de novembre 2025, ce comportement a changé :

• Les filtres d’autorisation ACL s’appliquent désormais même lorsqu’on utilise uniquement des clés API de service ou l’authentification Entra dans toutes les versions qui prennent en charge ACL.
• Si le jeton utilisateur est omis, le contenu protégé par la liste de contrôle d’accès n’est pas retourné.
• Pour afficher tous les documents pour le dépannage, vous devez inclure explicitement l’en-tête elevated-read lorsque vous utilisez la version 2026-05-01-preview ou ultérieure de l’API REST.

Cette mise à jour permet de protéger le contenu lorsque les applications n’appliquent pas les meilleures pratiques pour la validation des jetons.

Contenu connexe

• Tutoriel : Indexer les métadonnées d’autorisation à partir d’ADLS Gen2 et interroger avec des résultats filtrés par autorisation (préversion)
• Indexation des listes de contrôle d’accès aux documents (ACL) à l’aide des API REST Push (préversion)
• Utiliser un indexeur ADLS Gen2 pour ingérer les métadonnées d’autorisation et filtrer les résultats de recherche en fonction des droits d’accès utilisateur (préversion)
• Utilisez un indexeur de blob ou une source de connaissances pour importer les métadonnées des scopes RBAC
• Utiliser un indexeur SharePoint pour ingérer les métadonnées d’autorisation et filtrer les résultats de recherche en fonction des droits d’accès utilisateur (préversion)