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)

L’ingestion des métadonnées d’autorisation de SharePoint (version préliminaire) utilise un indexeur Recherche Azure AI pour conserver les métadonnées d’autorisation, telles que les listes de contrôle d’accès (ACL), en plus des autres contenus provenant de SharePoint dans Microsoft 365. L’indexeur stocke les autorisations sous forme de métadonnées sur chaque document indexé. Au moment de la requête, les utilisateurs reçoivent uniquement les documents auxquels ils sont autorisés à accéder.

Conditions préalables

• Recherche Azure AI sur un niveau facturable (De base ou supérieur) dans n’importe quelle région.

• SharePoint dans Microsoft 365 sites, bibliothèques, dossiers et fichiers avec des autorisations configurées.

• Effectuez toutes les étapes de configuration de la documentation de l’indexeur SharePoint, en appliquant les exigences spécifiques à la liste de contrôle d’accès décrites dans cet article.

• Configurez les autorisations d’application Microsoft Entra et les informations d’identification appropriées pour votre scénario. Consultez le scénario des autorisations par ACL. L’ingestion des ACL nécessite des autorisations d’application. Les autorisations déléguées ne sont pas prises en charge. Pour en savoir plus sur le choix entre les autorisations d’application et les autorisations déléguées, consultez Choisir votre configuration d’autorisations.

• API REST version 2026-08-01-preview ou un package de SDK d’évaluation équivalent.

Limitations

• Les mises à jour incrémentielles de liste de contrôle d’accès nécessitent l’API REST 2026-05-01-preview ou une version ultérieure. Dans les versions antérieures de l’API en préversion, le système capture uniquement les listes de contrôle d’accès sur la première ingestion de chaque élément. Les modifications d’autorisation ultérieures nécessitent une réindexation explicite. Pour connaître les étapes de migration, consultez Synchroniser les autorisations entre le contenu indexé et le contenu source.

• Les modifications des autorisations au niveau du parent ne sont pas prises en compte automatiquement lors des exécutions ultérieures de l’indexeur. Pour connaître les options d’actualisation, consultez Synchroniser les autorisations entre le contenu indexé et le contenu source.

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

• Les fonctionnalités suivantes ne sont pas prises en charge dans cette préversion :

  • Politiques de gestion de l'information de SharePoint applicables à l'accès des utilisateurs. Le système n’évalue pas, n’ingère pas ou n’honore pas ces stratégies au moment de la requête.

  • Liens partageables délimités à « Tout le monde » ou « Personnes de votre organisation ». Seuls les liens limités à « Personnes spécifiques » sont pris en charge.

  • Les groupes SharePoint (tels que les groupes Propriétaires, Membres et Visiteurs) sont pris en charge à compter de l’API REST 2026-05-01-preview. Consultez Configurer la prise en charge des groupes SharePoint. Dans les versions antérieures de l’API en préversion, seuls les groupes SharePoint qui se résolvent en groupes Microsoft Entra sont pris en charge.

• Les fonctionnalités d'indexeur suivantes ne prennent pas en charge l'héritage des autorisations dans les documents indexés provenant de SharePoint. 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 SharePoint.

  • Cache d’enrichissement de l’indexeur

  • Sessions de débogage

Prise en charge du modèle d’autorisation SharePoint

Cette préversion prend en charge les listes de contrôle d’accès de base pour les documents, les éléments de liste et les pages de site ASPX modernes.

Relations de groupe prises en charge

La transitivité des groupes Microsoft Entra s’applique au sein de Microsoft Entra. Elle ne développe pas les groupes Microsoft Entra qui sont membres de groupes SharePoint.

Évaluation des autorisations hiérarchiques

Les permissions de SharePoint héritent de la hiérarchie du Site → Bibliothèque → Dossier → Fichier, sauf si l’héritage est rompu.

Pendant l’ingestion, l’indexeur rassemble les identificateurs d’utilisateur et de groupe (ID) à chaque niveau et calcule la liste de contrôle d’accès effective pour chaque fichier.

Autorisations par scénario ACL

Les Microsoft Entra autorisations d’application et le type d’informations d’identification requis pour l’ingestion de liste de contrôle d’accès dépendent des types d’éléments et des types de groupes que vous indexez. Dans l’enregistrement de l’application, toutes les autorisations sont ajoutées sous Autorisations de l’API>Ajouter une autorisation, et les informations d’identification fédérées sont ajoutées sous Certificats & secrets>Informations d’identification fédérées. Pour obtenir des instructions détaillées et des captures d’écran, consultez Step 3 : Créer une inscription d’application Microsoft Entra et Configurer l’application inscrite avec une identité managée.

Les informations d’identification fédérées authentifient l’application à l’aide d’une identité managée approuvée au lieu d’une clé secrète client. Les mêmes informations d’identification fédérées couvrent à la fois l’ingestion (indexeur) et l’évaluation au moment de la requête des groupes de sites SharePoint. Pour connaître les étapes de configuration, consultez Configuration de l’application inscrite avec une identité managée.

Avant d’activer l’ingestion de liste de contrôle d’accès

Effectuez ces étapes sur votre application de Microsoft Entra inscrite :

1. Identifiez votre scénario dans le tableau précédent en fonction de ce que vous prévoyez d’indexer (fichiers de bibliothèque de documents, éléments de liste, pages de site ASPX) et selon que les groupes de sites SharePoint doivent être respectés.
2. Ouvrez l’enregistrement de votre application dans le centre d’administration Microsoft Entra et accédez à Autorisations d’API>Ajouter une autorisation.
3. Ajoutez les autorisations Microsoft Graph répertoriées pour votre scénario. Accordez le consentement de l’administrateur.
4. Si votre scénario nécessite également des autorisations SharePoint, sélectionnez Add une autorisation à nouveau, choisissez l’API SharePoint et ajoutez Sites.FullControl.All (ou Sites.Selected). Accordez le consentement de l’administrateur.
5. Configurez les informations d’identification :
   • Pour les scénarios utilisant uniquement Microsoft Graph, vous pouvez utiliser soit un secret client (Certificates & secrets>Client secrets), soit des informations d’identification fédérées.
   • Pour tout scénario qui inclut des autorisations SharePoint, ajoutez des informations d’identification fédérées sous Certificates & secrets Informations d’identification fédérées. Consultez Configuration de l’application enregistrée avec une identité managée.
6. Accordez à l’application l’accès aux sites SharePoint cibles (particulièrement important lorsque vous utilisez Sites.Selected pour l’accès étendu) afin qu’il puisse lire le contenu et les autorisations que vous souhaitez indexer.

Rechercher les identificateurs de Microsoft Entra corrects

Chaque identificateur apparaît à un emplacement différent dans le portail Azure et correspond à un champ de configuration spécifique. Utilisez cette section comme référence lors de la configuration de l’ingestion des ACL SharePoint avec des informations d’identification fédérées. Ces identificateurs sont mentionnés dans Configurer la prise en charge des groupes SharePoint et dans la chaîne de connexion de la source de données.

ID de l’application d’informations d’identification fédérées

Dans la chaîne de connexion de la source de données FederatedCredentialApplicationId et dans la définition de l’index federatedCredentialId, utilisez le propre ID d’application (client) de l’identité managée, et non l’ID de l’application d’ingestion.

Identité managée affectée par le système :

1. Accédez à votre service Recherche Azure AI.
2. Sélectionnez Sécurité + mise en réseau>Identité.
3. Sous l’onglet Affecté par le système, notez l’ID d’objet (principal).
4. Accédez à Microsoft Entra ID>Gérer>Applications d’entreprise.
5. Recherchez le nom de votre service de recherche ou collez l’ID d’objet (principal) dans la zone de recherche.
6. Sélectionnez le résultat et ouvrez Propriétés. Copiez l’ID d’application indiqué ici, qui est la valeur de FederatedCredentialApplicationId la source de données et federatedCredentialId de l’index.

Identité managée affectée par l’utilisateur :

1. Accédez à la ressource d’identité managée affectée par l’utilisateur.
2. Sélectionnez Paramètres>Propriétés.
3. Copiez l’ID client, qui est la valeur de FederatedCredentialApplicationId la source de données et federatedCredentialId de l’index.

Configurez votre service de recherche pour l’ingestion des listes de contrôle d’accès (ACL) et leur application au moment de la requête

Ces étapes configurent votre service de recherche pour l'ingestion d'ACL et activent le respect des ACL au moment de la requête.

Choisir où renseigner les champs ACL

L’emplacement où vous mappez les champs de métadonnées ACL dépend du fait que l’indexeur écrit un document par élément source ou plusieurs blocs par élément source.

Dans tous les scénarios de fragmentation, chaque fragment doit contenir les champs ACL. Les filtres d’autorisation s’appliquent par document, de sorte qu’un bloc manquant de champs ACL ne peut pas être retourné à l’appelant droit.

1. Configuration de la source de données

Cette section constitue un complément au guide de base Étape 4 : Créer une source de données. Définissez indexerPermissionOptions dans la définition de source data pour permettre l’indexation de userIds et groupIds à partir de documents SharePoint.

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. Ajouter des champs d’autorisation à la définition d’index

Ajoutez des champs à votre définition de schéma d’index pour stocker les listes de contrôle d’accès et prendre en charge le filtrage au moment des requêtes.

{
  "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 }
  ],
  "permissionFilterOption": "enabled"
}

Définissez l’attribut retrievable à true uniquement pendant le développement pour vérifier les valeurs. Vous pouvez modifier le paramètre de capacité de récupération (retrievable) de true à false sans nécessiter de reconstruction d'index.

3. Configurer les projections d’index dans votre ensemble de compétences (le cas échéant)

Lorsque la segmentation est activée, le document parent n’est pas écrit dans l’index lorsque projectionMode c’est skipIndexingParentDocuments. Reportez les métadonnées de liste de contrôle d’accès sur chaque segment via indexProjections.selectors[].mappings.

Si votre indexeur utilise un ensemble de compétences avec un segment de données, tel que la compétence Fractionnement de texte lors de l’activation de la vectorisation intégrée, veillez à mapper les propriétés ACL à chaque bloc à l’aide de projections d’index. Les // lignes de l’exemple suivant sont des annotations illustrantes et ne sont pas valides JSON. Supprimez-les avant de soumettre la demande.

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-08-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" } // include when the index has sharePointConnectorAppRegistration (SharePoint groups support)
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

Les mappages UserIds, GroupIds et SharePointSiteUrl lisent les métadonnées de niveau source émises par l’indexeur SharePoint (/document/metadata_*) et écrivent les valeurs sur chaque segment.

4. Configurer les mappages de champs de l’indexeur pour les ACL (listes de contrôle d’accès)

Utilisez des mappages de champs d’indexeur lorsque l’indexeur écrit un document par élément source (aucune segmentation) ou lorsque vous conservez un index parent distinct en même temps qu’un index de bloc. Si votre ensemble de compétences fractionne les documents dans un index cible unique avec projectionMode: skipIndexingParentDocuments, les mappages de champs indiqués ici sont remplacés par le indexProjections.mappings de l’étape précédente pour l’index de segments.

Outre votre configuration de indexer requise, mappez les champs ACL de métadonnées brutes de SharePoint à vos champs d’index.

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

5. Exécuter l’indexeur

Les métadonnées ACL sont ingérées lorsque l’indexeur s’exécute. Après avoir créé ou mis à jour l’indexeur (voir l’étape 6 : Créer un indexeur), déclenchez une exécution afin que l’indexeur ingère des ACL en même temps que le contenu.

POST https://[service name].search.windows.net/indexers/[indexer-name]/run?api-version=2026-08-01-preview
api-key: [admin key]

Si vous avez activé l’ingestion des listes de contrôle d’accès sur un indexeur existant qui a déjà indexé des éléments, appelez /resync avec options: ["permissions"] pour renseigner les listes de contrôle d’accès de ces éléments, ou /resetdocs pour réextraire des éléments spécifiques.

6. Vérifiez l’ingestion des ACL

Pour confirmer que les valeurs ACL sont correctement renseignées :

1. Définissez temporairement retrievable sur true pour UserIds et GroupIds dans la définition de votre index. La modification retrievable ne nécessite pas de reconstruction d’index.
2. Exécutez une requête de lecture privilégiée qui sélectionne UserIds et GroupIds, puis vérifiez que les collections ne sont pas vides. Pour les scénarios segmentés, vérifiez que chaque bloc comporte les deux champs.
3. Retournez retrievable à false après vérification.

Configurer la prise en charge des groupes SharePoint

À partir de l’API REST 2026-05-01-preview, l’indexeur SharePoint peut indexer les appartenances aux groupes de sites SharePoint (propriétaires, membres, visiteurs et groupes de sites personnalisés). Ces groupes sont pris en compte au moment de la requête. Les ID de groupe SharePoint sont renvoyés dans le champ metadata_group_ids avec le préfixe spg: afin de les distinguer des ID d’objet des groupes Microsoft Entra.

Cette procédure pas à pas est autonome : effectuez les étapes dans l’ordre pour configurer l’index, les mappages des champs de l’indexeur et interroger l’index avec l’application des groupes de sites SharePoint.

Les composants suivants fonctionnent ensemble pour permettre la résolution des groupes de sites SharePoint :

1. Prérequis

• Indexeur SharePoint déjà configuré pour l’ingestion des ACL. Consultez Configurer les mappages de champs de l’indexeur pour les listes de contrôle d’accès.
• Inscription d’application Microsoft Entra avec des informations d’identification d’identité fédérée. Consultez Configuration de l’application enregistrée avec une identité managée.
• API 2026-05-01-preview REST ou version ultérieure.

2. Configurer l’index

Ajoutez la sharePointConnectorAppRegistration configuration et le SharePointSiteUrl champ en même temps que les UserIdsGroupIds champs de filtre d’autorisation, de sorte que la forme d’index complète se trouve à un seul endroit. Conservez permissionFilterOption: "enabled".

PUT https://{service}.search.windows.net/indexes/{index}?api-version=2026-08-01-preview
{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
     "tenantId": "<sharepoint-tenant-id>"
  },
  "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": "SharePointSiteUrl", "type": "Edm.String", "sharepointSiteUrl": true, "filterable": false, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

3. Configurer les mappages de champs de l’indexeur

Mappez les champs de métadonnées SharePoint aux champs d’index dans un seul bloc de mappage combiné. Les deux premiers mappages sont les mêmes que ceux utilisés pour l’ingestion ACL standard ; le troisième mappage active la résolution des groupes SharePoint.

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",             "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids",            "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_spo_site_url",  "targetFieldName": "SharePointSiteUrl" }
  ]
}

Si votre jeu de compétences fractionne les documents (par exemple, avec la compétence Fractionnement de texte pour la vectorisation intégrée), projetez SharePointSiteUrl sur chaque segment via indexProjections.mappings à la place. Consultez Choisir où renseigner les champs ACL.

4. Interroger l’index

Aucune modification côté client n’est requise. Le même jeton x-ms-query-source-authorization applique à la fois le contrôle des groupes de sites Microsoft Entra et de SharePoint. Le service de recherche résout côté serveur les appartenances aux groupes SharePoint à l’aide de sharePointConnectorAppRegistration dans l’index.

Pour la structure de la requête, consultez l’exemple de requête générale et l’exemple spécifique à SharePoint avec application du groupe de sites SharePoint.

5. Vérifier

Pour confirmer que les ID de groupe SharePoint ont bien été ajoutés à l’index, exécutez une requête elevated-read qui sélectionne GroupIds et recherchez dans la réponse les valeurs préfixées par spg:.

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

À compter de l’API REST 2026-05-01-preview, les modifications de liste de contrôle d’accès pour les éléments disposant d’autorisations uniques sont détectées et actualisées sur chaque exécution réussie de l’indexeur. L’indexeur utilise les jetons de modification de SharePoint pour prendre en compte, de manière incrémentielle, les ajouts et les suppressions d’attributions de rôles, de la même façon qu’il prend en compte les modifications de contenu.

Certains scénarios nécessitent toujours une actualisation explicite :

Réinitialiser des documents spécifiques

Vous pouvez réinitialiser des documents spécifiques pour ingérer entièrement du contenu et des listes de contrôle d’accès.

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

Resynchroniser les listes de contrôle d’accès sur la source de données complète

Vous pouvez resynchroniser le contenu ACL du jeu de données complet après l’ingestion initiale. Pour réussir pleinement, cette opération nécessite une exécution d’indexeur après l’achèvement.

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

Après avoir indexé vos données et listes de contrôle d’accès, vous pouvez interroger l’index.

Résolution des problèmes

Pour les résultats manquants, inattendus ou ayant échoué au moment de la requête après l’indexation des métadonnées de liste de contrôle d’accès, consultez Résoudre les problèmes de filtrage des autorisations SharePoint.

Contenu connexe

• Indexer le contenu SharePoint dans la recherche Azure AI (aperçu)
• Application de l’ACL au moment de la requête