Indexation des listes de contrôle d’accès aux documents (ACL) à l’aide des API REST Push (préversion)

L’ingestion d’autorisations au niveau du document via les API REST push (préversion) vous permet d’indexer des documents avec leurs listes de contrôle d’accès associées (ACL) et les rôles RBAC (Container Role-Based Access Control). Lorsque vous envoyez du contenu à un index Recherche Azure AI via les API REST Push, le service conserve ces autorisations sur le contenu indexé et les applique au moment de la requête.

Les principales fonctionnalités sont les suivantes :

• Contrôle flexible des pipelines d’ingestion.
• Schéma standardisé pour les métadonnées d’autorisations.
• Prise en charge des autorisations hiérarchiques, telles que les listes de contrôle d’accès au niveau du dossier.

Cet article explique comment utiliser l’API REST Push pour indexer les métadonnées d’autorisation au niveau du document dans Recherche Azure AI. Ce processus prépare votre index à interroger et à appliquer les autorisations de l’utilisateur final sur les résultats de la recherche.

Conditions préalables

• Contenu avec des métadonnées de liste de contrôle d'accès issues de Microsoft Entra ID ou d'un autre système ACL de style POSIX. Pour les champs ACL userIds et groupIds, utilisez des ID d’objet Microsoft Entra (GUID), et non des UPN ou des adresses e-mail. Les ID d’objet stables garantissent une correspondance d’identité fiable au moment de la requête, même si les attributs d’annuaire changent.

• L’API REST version la plus récente ou un package de Kit de développement logiciel (SDK) Azure en préversion fournissant des fonctionnalités équivalentes.

• Un schéma d’index avec permissionFilterOption activé, accompagné des attributs de champ permissionFilter destinés à stocker les autorisations des documents.

Limitations

• Un champ ACL ayant un type de filtre d’autorisation userIds ou groupIds peut contenir au maximum 1 000 valeurs.

• Un index peut contenir au maximum cinq valeurs uniques parmi les champs de type rbacScope sur tous les documents. Il n’existe aucune limite quant au nombre de documents qui partagent la même valeur .rbacScope

• Un champ existant peut être mis à jour pour inclure une affectation pour le permissionFilter filtrage de métadonnées ACL ou RBAC intégré. Pour activer le filtrage sur un index existant, ajoutez de nouveaux champs ou mettez à jour les champs existants pour inclure une permissionFilter valeur.

• Un seul champ de chaque permissionFilter type (un de groupIds, userIdset rbacScope) peut exister dans un index.

• Chaque permissionFilter champ doit avoir filterable défini à true.

• L’application des autorisations lors de l’exécution de la requête reflète les valeurs ACL les plus récemment écrites dans l’index. Si les autorisations sources changent, ces mises à jour ne sont pas reflétées tant que vous n’avez pas modifié ou mis à jour les documents concernés. Planifiez la réingestion incrémentielle ou les mises à jour partielles pour maintenir les listes de contrôle d’accès à jour.

• Cette fonctionnalité n’est actuellement pas prise en charge dans le portail Azure.

Créer un index avec des champs de filtre d’autorisation

L’indexation des listes de contrôle d’accès et des métadonnées RBAC avec l’API REST nécessite la configuration d’un schéma d’index qui active les filtres d’autorisation et possède des champs avec des attributions de filtre d’autorisation.

Tout d’abord, ajoutez permissionFilterOption. Les valeurs valides sont enabled ou disabled, et vous devez la définir sur enabled. Vous pouvez le passer en mode disabled si vous souhaitez désactiver la fonctionnalité de filtre de permissions au niveau de l’index.

Ensuite, créez des champs de chaîne pour vos métadonnées d’autorisation et incluez permissionFilter. Rappelez-vous que vous pouvez avoir l’un de chaque type de filtre d’autorisation.

Voici un exemple de schéma de base qui inclut tous les permissionFilter types :

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

Pour les référentiels d’entreprise, tels que SharePoint Online, résolvez les autorisations au niveau du document ou au niveau du dossier pour Microsoft Entra ID d’objet utilisateur et de groupe pendant l’ingestion avant d’appeler l’API Push. Vous devez ensuite stocker ces ID dans les champs d’autorisation correspondants.

Exemple d’indexation d’API REST

Une fois que vous avez un index avec des champs de filtre d’autorisation, vous pouvez remplir ces valeurs à l’aide de l’API d’indexation Push, comme n’importe quel autre champ de document. Voici un exemple utilisant le schéma d’index spécifié, où chaque document spécifie l’action d’indexation, le champ clé (DocumentId) et les champs d’autorisation. Les documents doivent également inclure du contenu, mais ce champ est omis dans cet exemple pour la concision.

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["all"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

Règles de résolution des accès ACL

Cette section explique comment le système détermine l’accès aux documents d’un utilisateur en fonction des champs d’autorisation de chaque document. Ces champs sont soit des ACL (userIds et groupIds, où groupIds inclut des groupes de sécurité et des groupes Microsoft 365), soit une portée RBAC (rbacScope). Azure évalue l’étendue RBAC et les ACL dans un ordre défini, conformément au modèle d’autorisation ADLS Gen2.

Un utilisateur obtient l’accès en remplissant l’une des conditions suivantes : une entrée correspondante userIds ou groupIds, ou une affectation à un rôle Azure admissible pour le rbacScope. Pour en savoir plus sur la manière dont les identités des appelants sont fournies lors de la requête, consultez Application des ACL et du RBAC au moment de la requête.

Valeurs de liste de contrôle d’accès spéciales « all » et « none »

Les champs ACL, tels que userIds et groupIds, contiennent généralement des listes de GUID (identificateurs globaux uniques) qui identifient les utilisateurs et les groupes ayant accès au document. Deux valeurs de chaîne spéciales, « all » et « none », sont prises en charge pour ces types de champs ACL. Ces valeurs agissent comme des filtres étendus pour contrôler l’accès au niveau global, comme indiqué dans le tableau suivant.

Étant donné qu’un utilisateur doit correspondre à un seul type de champ, la valeur spéciale « all » accorde un accès public indépendamment des autres valeurs de champ ACL. En revanche, définir userIds sur « none » ou sur un tableau vide indique qu'aucun utilisateur n'est autorisé à accéder au document en fonction de l’ID utilisateur. Ils peuvent toujours être autorisés à accéder grâce à l’ID de groupe correspondant ou aux métadonnées RBAC.

Exemple de contrôle d’accès

Cet exemple montre comment les règles d’accès aux documents sont résolues en fonction des valeurs de champ d’autorisation dans userIds, groupIdset rbacScope. Pour une lisibilité, ce scénario utilise des alias tels que « user1 » et « group1 » au lieu de GUID ; en production, utilisez des ID d’objet Microsoft Entra (GUID).

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