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)

Azure Data Lake Storage (ADLS) Gen2 prend en charge l’accès par utilisateur aux répertoires et aux fichiers via access control lists (ACL) et role-based access control (Azure RBAC). Le contrôle d'accès basé sur les attributs (Azure ABAC) n'est pas pris en charge.

Recherche Azure AI peut ingérer ces métadonnées d’autorisations (préversion) avec le contenu des documents à l’aide d’une API REST en préversion. Les utilisateurs qui n’ont pas accès à un répertoire ou un fichier dans le stockage ne voient pas les documents correspondants dans les résultats de recherche. Il s’agit de l’une des plusieurs stratégies de contrôle d’accès au niveau de document dans Recherche Azure AI.

Cet article explique comment configurer un indexeur ADLS Gen2 ou une source d’informations d’objets blob ADLS Gen2 pour récupérer automatiquement les métadonnées d’autorisation dans un index de recherche. Il complète les données d’index d’ADLS Gen2 et crée une source de connaissances sur les blobs pour ADLS Gen2, avec des informations spécifiques à l’ingestion d’autorisations. Pour envoyer manuellement des métadonnées d’autorisation, consultez les listes de contrôle d’accès du document Index à l’aide de l’API Push.

Conditions préalables

• Microsoft Entra ID authentification et autorisation. Les services et les applications doivent se trouver dans le même locataire. Les utilisateurs peuvent se trouver dans différents locataires tant que tous les locataires utilisent Microsoft Entra ID. Les attributions de rôles sont utilisées pour chaque connexion authentifiée.

• Recherche Azure AI sur un niveau facturable (De base ou supérieur) dans n’importe quelle région. Le service de recherche doit avoir un accès en fonction du rôle activé et une identité managée affectée par le système ou affectée par l’utilisateur.

• Objets blob ADLS Gen2 dans un espace de noms hiérarchique, avec des autorisations utilisateur accordées par le biais d’ACL ou de rôles.

• API REST version 2025-05-01-preview ou ultérieure pour l’ingestion des permissions de l’indexeur. API REST version 2025-11-01-preview ou version ultérieure pour la prise en charge des sources de connaissances. Utilisez la dernière API REST en préversion ou un package de sdk en préversion qui prend en charge les filtres d’autorisation.

Limitations

• Le portail Azure ne prend pas en charge cette fonctionnalité.

• Les limites ADLS Gen2 sur les attributions de rôles et les entrées de liste de contrôle d’accès s’appliquent.

• Les catégories d’identité ACL owning users, owning groups, et Other (all) ne sont pas prises en charge pendant l’aperçu. Utilisez à la place les affectations named users et named groups.

• Les fonctionnalités d’indexeur suivantes ne prennent pas en charge l’héritage des autorisations dans les documents indexés provenant d’ADLS Gen2. Si vous utilisez l’une de ces fonctionnalités dans un ensemble de compétences ou un indexeur, les autorisations au niveau du document ne sont pas incluses dans le contenu indexé.

  • Compétence d’API web personnalisée

  • Base de connaissances, y compris le magasin d’actifs requis pour le service d’images (version préliminaire) dans la récupération agentique. Par conséquent, le service d’image n’est pas pris en charge pour les sources de connaissances qui ingèrent des ACL ou des étendues RBAC.

  • Cache d’enrichissement de l’indexeur

  • Sessions de débogage

Prise en charge du modèle d’autorisation

Cette section compare les fonctionnalités de contrôle d’accès au niveau du document entre ADLS Gen2 et Recherche Azure AI. Il explique quels mécanismes de contrôle d’accès Azure Data Lake Storage (ADLS) Gen2 AI Search prend en charge ou mappe. Cela vous aide à comprendre comment les autorisations sont appliquées au niveau du document.

Au moment de la requête, Recherche Azure AI évalue d’abord le RBAC au niveau du conteneur, puis vérifie les entrées ACL au niveau du document. L’accès est accordé si un mécanisme l’autorise.

À propos des autorisations hiérarchiques ACL (liste de contrôle d'accès)

Les indexeurs et les sources de connaissances peuvent récupérer des affectations de contrôle d'accès à partir du conteneur spécifié et de tous les répertoires menant à chaque fichier en suivant le flux d’évaluation d’accès hiérarchique ADLS Gen2. Les listes d’accès effectives finales pour chaque fichier sont calculées et les différentes catégories d’accès sont indexées dans les champs d’index correspondants.

Par exemple, dans les scénarios courants ADLS Gen2 liés aux autorisations avec le chemin de fichier /Oregon/Portland/Data.txt.

L’indexeur ou la source de connaissances collecte des listes de contrôle d’accès à partir de chaque conteneur et répertoire. Il détermine ensuite l’accès effectif aux niveaux inférieurs et continue jusqu’à ce qu’il résolve les autorisations pour chaque fichier.

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

Configurer ADLS Gen2

Un indexeur ou une source de connaissances peut récupérer des listes de contrôle d’accès sur un compte de stockage si les critères suivants sont remplis. Pour plus d’informations sur les affectations de contrôle d'accès (ACL), consultez les affectations de contrôle d'accès ADLS Gen2.

Autorisation

Pour l’exécution de l’indexeur, votre identité de service de recherche doit disposer de l’autorisation Lecteur de données Blob de stockage.

Si vous effectuez des tests localement, vous devriez également disposer d'une assignation de rôle Lecteur de données Blob de stockage. Pour plus d’informations, consultez Connect to stockage Azure using a managed identity.

Autorisations de conteneur racine :

1. Attribuez tous les ensembles Group et User (principaux de sécurité) au conteneur racine / avec les autorisations Read et Execute.

2. Vérifiez que les deux Read et Execute sont ajoutés en tant qu'« autorisations par défaut » afin qu’elles se propagent automatiquement aux fichiers et répertoires nouvellement créés.

Propager les autorisations vers le bas de la hiérarchie de fichiers

Bien que les nouveaux répertoires et fichiers héritent des autorisations, les répertoires et fichiers existants n’héritent pas automatiquement de ces affectations.

Utilisez l’outil ADLS Gen2 pour appliquer des listes de contrôle d’accès de manière récursive pour la propagation des affectations sur le contenu existant. Cet outil propage les affectations de liste de contrôle d’accès du conteneur racine à tous les répertoires et fichiers sous-jacents.

Supprimer les autorisations excédentaires

Après avoir appliqué des listes de contrôle d’accès de manière récursive, passez en revue les autorisations pour chaque répertoire et fichier.

Supprimez tout Group ou User ensemble qui ne doit pas avoir accès à des répertoires ou fichiers spécifiques. Par exemple, supprimez User2 sur le dossier Portland/, et pour le dossier Idaho, supprimez Group2 et User2 de ses affectations, et ainsi de suite.

Exemple de structure des affectations ACL

Voici un diagramme de la structure d'attribution ACL pour la hiérarchie de répertoires fictifs dans la documentation ADLS Gen2.

Mises à jour des affectations des listes de contrôle d'accès avec le temps

Au fil du temps, à mesure que toutes les nouvelles affectations de liste de contrôle d’accès sont ajoutées ou modifiées, répétez les étapes précédentes pour garantir l’alignement approprié de la propagation et des autorisations. Les autorisations mises à jour dans ADLS Gen2 sont mises à jour dans l’index de recherche lorsque vous réingèrez le contenu à l’aide de l’indexeur ou de la source de connaissances.

Configurer Recherche Azure AI

Rappelez-vous que le service de recherche doit avoir :

• Accès en fonction du rôle activé
• Identité managée configurée

Autorisation

Pour l’indexation, le client qui émet l’appel d’API doit disposer de l’autorisation Contributeur du service de recherche pour créer des objets, l’autorisation Contributeur aux données d’index de recherche pour effectuer l’importation de données et le lecteur de données d’index de recherche pour interroger un index.

Si vous effectuez des tests localement, vous devez disposer des mêmes attributions de rôles. Pour plus d'informations, consultez Connexion à Recherche Azure AI en utilisant des rôles.

Configurer une source de connaissances

Si vous utilisez une source de connaissances, les définitions de la source de connaissances sont utilisées pour générer un pipeline d’indexation complet (indexeur, source de données et index). Les affectations d'ACL sont détectées et automatiquement incluses dans l'index généré. Il n’est pas nécessaire de modifier l’un des objets générés si vous souhaitez l’héritage d’autorisation dans votre contenu indexé.

Points clés sur la configuration qui le rendent adapté à ce scénario :

• isADLSGen2 a la valeur true, répondant aux exigences de la source de données pour ce scénario.
• ingestionPermissionOptions spécifie les ID d’utilisateur et de groupe.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

Configurer l’indexation basée sur l’indexeur

Si vous utilisez un indexeur, configurez-le, la source de données et l’index pour extraire les métadonnées d’autorisation à partir d’objets blob ADLS Gen2.

Créer la source de données

Cette section complète les données Index à partir d'ADLS Gen2 avec des informations spécifiques à l'ingestion des autorisations en même temps que le contenu du document dans un index Recherche Azure AI.

• Le type de source de données doit être adlsgen2.

• La source de données doit avoir indexerPermissionOptions avec userIds, groupIdset/ou rbacScope.

  • Pour rbacScope, configurez la chaîne de connexion avec le format d'identité gérée.

  • Pour les chaînes de connexion utilisant une identité managée affectée par l’utilisateur, vous devez également spécifier la identity propriété.

Exemple JSON avec identité managée par le système :

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

Exemple de schéma JSON avec une identité managée par l’utilisateur dans le chaîne de connexion :

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Créer des champs d’autorisation dans l’index

Dans Recherche Azure AI, vérifiez que votre index contient des définitions de champs pour les métadonnées d’autorisation. Les métadonnées d’autorisation peuvent être indexées quand indexerPermissionOptions elles sont spécifiées dans la définition de la source de données.

Attributs de schéma recommandés pour ACL (UserIds, GroupIds) et étendue RBAC :

• Champ Identificateur de l'utilisateur (ID) avec la valeur userIds permissionFilter.
• Champ Group IDs avec la valeur groupIds du filtre de permissions.
• Champ d’étendue RBAC avec la valeur de permissionFilter rbacScope.
• Propriété permissionFilterOption permettant d’activer le filtrage au moment de l’interrogation.
• Utiliser des champs de chaîne pour les métadonnées d’autorisation
• Définissez la filterable valeur true sur tous les champs.

Notez que retrievable est faux. Vous pouvez le définir lors du développement pour vérifier que les autorisations sont présentes, mais n’oubliez pas de revenir à false avant de le déployer dans un environnement de production.

Exemple de schéma JSON :

{
  ...
  "fields": [
    ...
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Configurer l’indexeur

Les mappages de champs au sein d’un indexeur définissent le chemin des données sur les champs d’un index. Les champs cibles et de destination qui varient selon le nom ou le type de données nécessitent un mappage de champ explicite. Les champs de métadonnées suivants dans ADLS Gen2 peuvent avoir besoin de mappages de champs si vous modifiez le nom du champ :

• metadata_user_ids (Collection(Edm.String)) : liste des ID d’utilisateur ACL.
• metadata_group_ids (Collection(Edm.String)) : liste des ID de groupe ACL.
• metadata_rbac_scope (Edm.String) : étendue RBAC du conteneur.

Spécifiez fieldMappings dans l’indexeur pour router les métadonnées d’autorisation vers les champs cibles pendant l’indexation.

Exemple de schéma JSON :

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Recommandations et meilleures pratiques

• Planifiez attentivement la structure de dossiers ADLS Gen2 avant de créer des dossiers.

• Organisez les identités en groupes et utilisez des groupes dans la mesure du possible, plutôt que d’accorder l’accès directement à des utilisateurs individuels. L’ajout continu d’utilisateurs individuels au lieu d’appliquer des groupes augmente le nombre d’entrées de contrôle d’accès qui doivent être suivies et évaluées. Le non-respect de cette meilleure pratique peut entraîner des mises à jour de métadonnées de sécurité plus fréquentes requises pour l’index car ces métadonnées changent, provoquant des retards accrus et des inefficacités dans le processus d’actualisation.

Synchroniser les autorisations entre le contenu indexé et le contenu source

L’activation de l’enrichissement ACL ou RBAC sur un indexeur ne fonctionne automatiquement que dans deux situations :

• La première exécution complète de l’indexeur/analyse des données : toutes les métadonnées d’autorisation qui existent à ce moment-là pour chaque document sont capturées.

• Les nouveaux documents ajoutés après l’activation de la prise en charge ACL/RBAC : leurs informations ACL/RBAC sont ingérées avec leur contenu.

Si vous modifiez les autorisations de document, telles que l’ajout d’un utilisateur à une liste de contrôle d’accès ou la mise à jour d’une attribution de rôle, la modification n’apparaît pas dans l’indexeur, sauf si vous demandez à l’indexeur d’analyser à nouveau les métadonnées d’autorisation du document.

Choisissez l’un des mécanismes suivants, en fonction du nombre d’éléments modifiés :

Exemple d’API Resetdocs (préversion) :

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

Exemple d’API Resync (préversion) :

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
} 

Suivi des suppressions

Pour gérer efficacement la suppression d’objets blob, assurez-vous que le suivi de la suppression est activé avant l’exécution de votre indexeur pour la première fois. Cette fonctionnalité permet au système de détecter les objets blob supprimés dans votre source et de les supprimer de l’index.

Contenu connexe

• Connectez-vous à Recherche Azure AI en utilisant des rôles
• Application de l'ACL et de l'application du RBAC en temps de requête
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API