ACL- en RBAC-afdwinging van querytijd in Azure AI Zoeken (preview)

Toegangsbeheer voor querytijd (preview) zorgt ervoor dat gebruikers alleen zoekresultaten ophalen waartoe ze gemachtigd zijn, op basis van hun identiteit, groepslidmaatschappen, rollen of kenmerken. Deze functionaliteit is essentieel voor veilige zakelijke zoek- en compliancegestuurde werkstromen.

Geautoriseerde toegang is afhankelijk van machtigingenmetagegevens die worden opgenomen tijdens het indexeren. Voor indexeergegevensbronnen met ingebouwde toegangsmodellen, zoals Azure Data Lake Storage (ADLS) Gen2 en SharePoint in Microsoft 365, kan een indexeerfunctie automatisch de metagegevens van machtigingen voor elk document ophalen. Voor andere gegevensbronnen moet u de nettolading van het document zelf samenstellen en moet de nettolading zowel inhoud als de bijbehorende machtigingsmetagegevens bevatten. Vervolgens gebruikt u de push-API's om de index te laden.

In dit artikel wordt uitgelegd hoe u query's instelt die machtigingenmetagegevens gebruiken om resultaten te filteren.

Voorwaarden

• Machtigingsmetagegevens moeten in filterable tekenreeksvelden staan. U gebruikt het filter niet in uw query's, maar de zoekmachine bouwt intern een filter om niet-geautoriseerde inhoud uit te sluiten.

• Machtigingsmetagegevens moeten bestaan uit POSIX-machtigingen die het toegangsniveau en de groeps- of gebruikers-id identificeren, of de resource-id van de container in ADLS Gen2 als u een RBAC-bereik gebruikt.

• Voor op ACL gebaseerde afdwinging met aangepaste gegevensopname slaat u userIds en groupIds op als Microsoft Entra-object-id's (GUID's) in filterbare velden. Bij het uitvoeren van een query vergelijkt de service de identiteiten in x-ms-query-source-authorization met die opgeslagen ID’s. Zie Toegangsbeheerlijsten voor documenten (ACL's) indexeren met behulp van de PUSH REST API's (preview) voor schemadetails.

• Afhankelijk van de gegevensbron:

  • Voor ADLS Gen2-gegevensbronnen moet u toegangsbeheerlijsten (ACL's) en/of Azure RBAC-rollen (op rollen gebaseerd toegangsbeheer) op containerniveau hebben geconfigureerd.
  • Voor Azure Blob-gegevensbronnen moet u roltoewijzingen voor de container hebben. U kunt een ingebouwde indexeerfunctie, een kennisbron of Push-API's gebruiken om metagegevens van machtigingen in uw index te indexeren.
  • Voor SharePoint gegevensbronnen moet u toegangsbeheerlijsten (ACL's) configureren. U kunt een built-in SharePoint indexeerfunctie gebruiken en configureren met ACL-opnamemogelijkheden. U kunt ook een geïndexeerde SharePoint kennisbron gebruiken en deze configureren om machtigingen op documentniveau af te dwingen. Op groepen gebaseerde machtigingen, waaronder Microsoft 365 Groepen, worden ondersteund wanneer ze worden opgenomen als Entra-object-id's. Groepsuitbreiding vindt plaats op het moment van query's via Microsoft Graph.

• Gebruik de latest preview REST API of een preview-pakket van een Azure SDK om een query uit te voeren op de index of kennisbron. Deze API-versie ondersteunt interne query's waarmee niet-geautoriseerde resultaten worden gefilterd.

Beperkingen

• Als de ACL-evaluatie mislukt (bijvoorbeeld de Graph API niet beschikbaar is), retourneert de service 5xx en wordt not een gedeeltelijk gefilterde resultatenset geretourneerd.

• De ACL-versheid is afhankelijk van de opnamemethode. Als u verouderde autorisatiebeslissingen wilt voorkomen, moet u plannen hoe elke bron machtigingen wijzigt in de index:

  • Een geplande SharePoint indexeerfunctie vernieuwt machtigingswijzigingen op itemniveau voor elke uitvoering. Wijzigingen aan een bovenliggend bereik (site, bibliotheek, lijst of map) die door onderliggende items worden geërfd, vereisen een nieuwe synchronisatie.
  • Een ADLS Gen2-indexeerfunctie vereist een hersynchronisatie om ACL's te vernieuwen.
  • Aangepaste gegevensopname of pushgegevensopname vereist dat u de betreffende documenten opnieuw opneemt.

• Voor documentzichtbaarheid zijn beide vereist:

  • De RBAC-rol van de aanroepende toepassing (autorisatieheader).
  • De gebruikersidentiteit die wordt doorgegeven door x-ms-query-source-authorization.

• Initiële query's op basis van ACL kunnen een hogere latentie ervaren in vergelijking met volgende aanvragen, vanwege overhead voor caching en machtigingsomzetting.

• Voor geïndexeerde SharePoint-inhoud wordt een Microsoft Entra-groep die is genest in een SharePoint-groep niet uitgebreid. Microsoft Entra transitieve groepsresolutie biedt geen ondersteuning voor deze gemengde relatie. Zie Ondersteunde groepsrelaties.

ACL-invoerlimieten per gegevensbron

Toegangsbeheerlijsten (ACL) bepalen hoeveel afzonderlijke machtigingsrecords kunnen worden gekoppeld aan een bestand, map of item in een verbonden gegevensbron. Elke vermelding vertegenwoordigt één gebruikers- of groepsidentiteit en de toegangsrechten die aan die identiteit zijn verleend (bijvoorbeeld Lezen, Schrijven of Uitvoeren).

Het maximum aantal ACL-vermeldingen dat wordt ondersteund door Azure AI Zoeken functionaliteit, is afhankelijk van het gegevensbrontype:

Azure Data Lake Storage Gen2 (ADLS Gen2): elk bestand of elke map kan maximaal 32 ACL-vermeldingenmachtigingen hebben. In deze context betekent een vermelding één principal (gebruiker of groep) met een specifieke machtigingenset. Voorbeeld: het toewijzen van "Iedereen" leestoegang en "Azure gebruikers" uitvoertoegang telt als twee ACL-vermeldingen.

SharePoint in Microsoft 365: SharePoint gegevensbron in de zoekfunctie ondersteunt maximaal 1000 machtigingsvermeldingen per bestand. Elke vermelding vertegenwoordigt een unieke gebruikers- of groepstoewijzing in de machtigingenlijst van het item. Dit verschilt van de algemene limieten voor unieke machtigingsbereiken per lijst of bibliotheek, waarmee wordt bepaald hoeveel items unieke machtigingen kunnen hebben.

Deze limieten bepalen hoe gedetailleerd Azure AI Zoeken machtigingen op itemniveau kan respecteren bij het indexeren of filteren van zoekresultaten. Als een item deze ACL-invoerlimieten overschrijdt, worden machtigingen buiten de limiet mogelijk niet afgedwongen tijdens het uitvoeren van query's.

Hoe afdwinging van querytijd werkt

In deze sectie vindt u de volgorde van bewerkingen voor afdwinging van ACL's tijdens het uitvoeren van query's. Bewerkingen variëren, afhankelijk van of u Azure RBAC-bereik of Microsoft Entra ID groep- of gebruikers-id's gebruikt.

1. Invoer van gebruikersmachtigingen

De eindgebruikertoepassing bevat een toegangstoken voor query's als onderdeel van de zoekqueryaanvraag en dat toegangstoken is doorgaans de identiteit van de gebruiker. De volgende tabel bevat de bron van de gebruikersmachtigingen die worden ondersteund door Azure AI Zoeken voor afdwinging van ACL's:

2. Beveiligingsfilterconstructie

Intern bouwt Azure AI Zoeken dynamisch beveiligingsfilters op basis van de opgegeven gebruikersmachtigingen. Deze beveiligingsfilters worden automatisch toegevoegd aan alle filters die bij de query kunnen worden geleverd als voor de index de optie machtigingsfilter is ingeschakeld.

Voor Azure RBAC zijn machtigingen lijsten met resource-id-tekenreeksen. Er moet een Azure roltoewijzing (Storage Blob Data Reader) zijn voor de gegevensbron die toegang verleent tot het token van de beveiligingsprincipaal in de autorisatieheader. Het filter verwijdert documenten als er geen roltoewijzing is voor de principal die gekoppeld is aan het toegangstoken in de aanvraag.

3. Resultaten filteren

Het beveiligingsfilter stemt de gebruikers-id's, groupIds en rbacScope van het verzoek efficiënt af op elke lijst met ACL's in elk document in de zoekindex om de resultaten te beperken tot degenen waartoe de gebruiker toegang heeft. Het is belangrijk om te weten dat elk filter onafhankelijk van elkaar wordt toegepast en dat een document wordt beschouwd als geautoriseerd als een filter slaagt. Als een gebruiker bijvoorbeeld toegang heeft tot een document via userIds, maar niet via groupIds, wordt het document nog steeds beschouwd als geldig en geretourneerd aan de gebruiker.

SharePoint groepen op querytijd

Vanaf de REST API-versie 2026-05-01-preview kan Azure AI Zoeken tijdens het uitvoeren van query’s rekening houden met lidmaatschappen van SharePoint-sitegroepen, zoals Owners, Members, Visitors en aangepaste sitegroepen. Als u dit scenario wilt inschakelen, moet de index het volgende bevatten:

• Een eigenschap sharePointConnectorAppRegistration die verwijst naar de federatieve identiteitsreferentie van de Microsoft Entra-toepassing die wordt gebruikt om SharePoint namens de gebruiker aan te roepen.
• Een veld dat is gemarkeerd met het kenmerk sharepointSiteUrl: true waarmee de SharePoint site-URL voor elk geïndexeerd item wordt opgeslagen (meestal SharePointSiteUrl en ingevuld vanuit het metadata_spo_site_url bronveld).

Tijdens de query gebruikt Azure AI Zoeken de geregistreerde toepassing en de site-URL op elk kandidaatdocument om de SharePoint-groep lidmaatschappen van de aanroepende gebruiker op die site op te lossen. De opgeloste groepen worden vergeleken met de spg:-voorvoegselwaarden die zijn opgeslagen in het groupIds filterveld voor machtigingen. Het voorvoegsel spg: onderscheidt SharePoint sitegroepen van Microsoft Entra groepsobject-id's, die zonder voorvoegsel worden opgeslagen.

Zie Configure SharePoint groups support voor configuratiedetails en -beperkingen.

Als SharePoint-machtigingsfiltering ontbrekende of onverwachte resultaten retourneert, raadpleegt u Problemen met SharePoint-machtigingsfiltering oplossen.

Voorbeeld: Query met afdwinging van de SharePoint-sitegroep

Het verzoek is identiek aan de standaardquery met ACL-afdwinging. De zoekservice gebruikt de sharePointConnectorAppRegistration van de index om namens de aanroeper het lidmaatschap van SharePoint-groepen te bepalen. Neem GroupIds op in de select-clausule om waarden met het voorvoegsel spg: in het antwoord weer te geven.

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"
}

Queryvoorbeeld

Hier volgt een voorbeeld van een queryaanvraag uit sample code. Het querytoken is een Microsoft Entra toegangstoken voor de querygebruiker.

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"
}

Verhoogde machtigingen voor het onderzoeken van onjuiste resultaten (preview)

Foutopsporingsquery's die machtigingenmetagegevens bevatten, kunnen problematisch zijn omdat zoekresultaten specifiek zijn voor elke gebruiker. Als ontwikkelaar of beheerder hebt u mogelijk verhoogde machtigingen nodig om resultaten te retourneren, ongeacht de machtigingsmetagegevens, zodat u problemen kunt onderzoeken met query's die onbevoegde inhoud retourneren.

Als u dit wilt onderzoeken, moet u het volgende kunnen doen:

• Bekijk de set documenten die de eindgebruiker kan weergeven op basis van de machtigingen van die gebruiker.

• Bekijk alle documenten in de index om te onderzoeken waarom sommige documenten mogelijk niet zichtbaar zijn voor de eindgebruiker.

U kunt deze taken uitvoeren door een aangepaste koptekst toe x-ms-enable-elevated-read: truete voegen aan een query.

Machtigingen voor leesverzoeken met verhoogde machtigingen

U moet inzendermachtigingen voor zoekindexgegevens of een aangepaste rol hebben met de machtiging Elevate Lezen.

Query's zijn een gegevensvlakbewerking, dus de aangepaste rol kan alleen bestaan uit machtigingen voor het atomische gegevensvlak. Voor een aangepaste rol voegt u de machtiging Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read toe.

Een koptekst met verhoogde leesrechten toevoegen aan een query

Nadat u machtigingen hebt ingesteld, kunt u de query uitvoeren. Het volgende voorbeeld is een queryaanvraag voor een zoekindex.

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
}

Belangrijke wijziging van het gedrag van ACL-functionaliteit in specifieke preview-API-versies

Voor REST API-versie 2025-11-01-preview retourneerden eerdere preview-versies 2025-05-01-preview en 2025-08-01-preview alle documenten bij het gebruik van een service-API key of geautoriseerde Entra-rollen, zelfs als er geen gebruikerstoken was opgegeven. Toepassingen die de aanwezigheid van een gebruikerstoken niet hebben gevalideerd, kunnen onbedoeld resultaten zichtbaar maken voor eindgebruikers als ze niet correct worden geïmplementeerd of aanbevolen procedures volgen.

Vanaf november 2025 is dit gedrag gewijzigd:

• ACL-machtigingsfilters zijn nu ook van toepassing wanneer u alleen service-API-sleutels of Entra-verificatie gebruikt in alle versies die ACL ondersteunen.
• Als het gebruikerstoken wordt weggelaten, wordt inhoud met ACL-beveiliging niet geretourneerd.
• Als u alle documenten voor probleemoplossing wilt weergeven, moet u de header met verhoogde leesbewerking expliciet opnemen wanneer u de REST API-versie 2026-05-01-preview of hoger gebruikt.

Deze update helpt om inhoud beveiligd te houden wanneer toepassingen geen aanbevolen procedures afdwingen voor tokenvalidatie.

Verwante inhoud

• Zelfstudie: Metagegevens van machtigingen van ADLS Gen2 indexeren en query's uitvoeren met resultaten die zijn gefilterd op machtigingen (preview)
• Documenttoegangsbeheerlijsten (ACL's) indexeren met behulp van de PUSH REST API's (preview)
• Een ADLS Gen2-indexeerfunctie gebruiken om metagegevens van machtigingen op te nemen en zoekresultaten te filteren op basis van gebruikerstoegangsrechten (preview)
• Gebruik een blob-indexeerder of kennisbron om RBAC-scope metadata in te voeren
• Een SharePoint indexeerfunctie gebruiken om metagegevens van machtigingen op te nemen en zoekresultaten te filteren op basis van gebruikerstoegangsrechten (preview)