Afdwinging van Microsoft Purview-gevoeligheidslabels tijdens query's in Azure AI Zoeken (preview)

Tijdens de query kan Azure AI Zoeken beleidsregels voor vertrouwelijkheidslabels (preview) afdwingen die zijn gedefinieerd in Microsoft Purview. Dit beleid omvat de evaluatie van EXTRACT gebruiksrechten die aan elk document zijn gekoppeld, zodat gebruikers alleen documenten kunnen ophalen waartoe ze toegang hebben.

Deze mogelijkheid breidt toegangsbeheer op documentniveau uit zodat deze overeenkomt met de informatiebeveiligings- en nalevingsvereisten die worden beheerd in Microsoft Purview.

Wanneer indexering van Purview-vertrouwelijkheidslabels is ingeschakeld, controleert Azure AI Zoeken de metagegevens van elk document tijdens de query. Hiermee worden toegangsfilters toegepast op basis van Purview-beleid om alleen resultaten te retourneren die de aanvragende gebruiker mag openen.

In dit artikel wordt uitgelegd hoe het afdwingen van vertrouwelijkheidslabels voor query's werkt en hoe u beveiligde zoekquery's kunt uitgeven.

Voorwaarden

• Voer alle stappen uit in Gebruik Azure AI Zoeken indexers om Microsoft Purview vertrouwelijkheidslabels in te voeren.

• Controleer of de Azure AI Zoeken-service de door het systeem toegewezen beheerde identiteit (niet een door de gebruiker toegewezen beheerde identiteit) heeft ingeschakeld en of deze de Content.SuperUser toewijzingen en UnifiedPolicy.Tenant.Read roltoewijzingen bevat. Afdwingen van querytijd is afhankelijk van labelmetagegevens die de indexeerfunctie alleen kan extraheren wanneer de door het systeem toegewezen identiteit de juiste configuratie heeft. Zie stap 1 in het installatieartikel van de indexeerfunctie.

• Zowel de Azure AI Zoeken-service als de gebruiker die de query uitgeeft, moet zich in dezelfde Microsoft Entra tenant bevinden.

• REST API-versie 2025-11-01-preview of nieuwer, of een gelijkwaardig preview-SDK-pakket, om de index te doorzoeken. Voor de uitgebreide leesmogelijkheid en controlelogboekregistratie van Purview is 2026-05-01-preview of hoger vereist.

• Verifieer query's met behulp van Azure op rollen gebaseerd toegangsbeheer (RBAC), niet API-sleutels. Wanneer Purview-vertrouwelijkheidslabels zijn ingeschakeld, wordt toegang tot API-sleutels beperkt tot het ophalen van indexschema's.

Beperkingen

• Gastaccounts en query's voor meerdere tenants worden niet ondersteund.

• Automatisch aanvullen en API's voorstellen worden niet ondersteund voor indexen met Purview-functionaliteit.

• Als de labelevaluatie mislukt, retourneert de service een specifieke HTTP-foutcode in plaats van een gedeeltelijke of niet-gefilterde resultatenset. Zie Queryfouten oplossen voor de volledige lijst met foutcodes en oorzaken.

• Het systeem evalueert alleen labels zoals ze bestonden op het moment van de laatste uitvoering van de indexeerfunctie. Recente labelwijzigingen zijn mogelijk pas zichtbaar als de volgende geplande herindex wordt uitgevoerd.

Hoe de handhaving van vertrouwelijkheidslabels voor query-tijd werkt

Wanneer u een query uitvoert op een index die Microsoft Purview vertrouwelijkheidslabels bevat, controleert Azure AI Zoeken het bijbehorende Purview-beleid voordat resultaten worden geretourneerd. Op deze manier retourneert de query alleen documenten waartoe het gebruikerstoken toegang heeft.

1. Invoer van gebruikersidentiteit en toepassingsrol

Bij het uitvoeren van query's valideert Azure AI Zoeken beide:

• De RBAC-rol van de aanroepende toepassing, die is opgegeven in de Authorization header. De minimaal vereiste rol is Search Index Data Reader. Raadpleeg de handleiding Azure AI Zoeken RBAC voor meer informatie.
• De gebruikersidentiteit via een token, opgegeven in de x-ms-query-source-authorization header.

Beide zijn vereist om zichtbaarheid op basis van labels te autoriseren.

2. Evaluatie van vertrouwelijkheidslabels

Wanneer een queryaanvraag wordt ontvangen, evalueert Azure AI Zoeken:

1. Het veld sensitivityLabel in elk geïndexeerd document (geëxtraheerd uit Microsoft Purview tijdens opname).
2. De effectieve Purview-machtigingen van de gebruiker, zoals gedefinieerd door Microsoft Entra ID- en Purview-labelbeleid.

Als de gebruiker niet is gemachtigd voor het vertrouwelijkheidslabel van een document met EXTRACT machtigingen, wordt dat document uitgesloten van de queryresultaten.

3. Filteren van resultaten beveiligen

Azure AI Zoeken past het beveiligingsfilter toe na alle door de gebruiker gedefinieerde filters en scorestappen.
Een document wordt alleen opgenomen in de uiteindelijke resultatenset als:

• De aanroepende toepassing heeft een geldige roltoewijzing (via RBAC) en
• Het gebruikersidentiteitstoken dat wordt vertegenwoordigd door x-ms-query-source-authorization is geldig en mag inhoud weergeven met het vertrouwelijkheidslabel van het document.

Als een van de voorwaarden mislukt, wordt het document weggelaten uit de resultaten.

Een gebruikerstoegangstoken verkrijgen

Als u een query wilt uitvoeren op Azure AI Zoeken met behulp van gebruikerscontext, moet u een toegangstoken verkrijgen dat de aangemelde gebruiker vertegenwoordigt. De methode die u gebruikt, is afhankelijk van of u lokaal test met uw eigen token, als u toegang hebt tot het brondocument of de toepassingsstroom implementeert waarvoor het token van de eindgebruiker moet worden doorgegeven.

Voor testscenario's

Voor lokale tests kunt u een toegangstoken voor gebruikers ophalen met behulp van Azure CLI:

$token = az account get-access-token `
  --resource https://search.azure.com `
  --query accessToken `
  --output tsv

Deze benadering maakt gebruik van uw huidige Azure CLI-aanmeldsessie, zodat u de context kunt gebruiken voor documenten waarvoor u via vertrouwelijkheidslabels EXTRACT machtigingen hebt toegewezen gekregen. Deze methode is alleen bedoeld voor ontwikkelings- en validatiescenario's.

Tokenverwerving voor OBO-scenario's

Toepassingen die de on-behalf-of-OBO-stroom implementeren, moeten tokens verkrijgen via Microsoft Entra ID met behulp van een ondersteunde verificatiebibliotheek, zoals de Microsoft Authentication Library (MSAL).

In OBO-scenario's vraagt u het token aan voor de downstream-API die de toepassing aanroept. Wanneer u bijvoorbeeld Azure AI Zoeken aanroept, wordt de resource-URI https://search.azure.com/.default.

De .default-scope vraagt alle gedelegeerde machtigingen aan waarvoor de toepassing vooraf toestemming heeft gegeven voor de opgegeven bron.

Machtigingen voor vertrouwelijkheidslabels, waaronder EXTRACT, worden niet weergegeven als OAuth-bereiken. De downstreamservice, zoals Azure AI Zoeken, evalueert deze machtigingen tijdens runtime op basis van de gebruikersidentiteit in het token en het toegepaste vertrouwelijkheidslabelbeleid.

Queryvoorbeeld

Hier is een voorbeeld van een queryverzoek dat gebruikmaakt van de afdwinging van Microsoft Purview-vertrouwelijkheidslabels.

Geef het applicatietoken door als bearer-token in de Authorization-header. Geef het gebruikerstoken door als de onbewerkte tokenwaarde in de x-ms-query-source-authorization header, zonder het Bearer voorvoegsel.

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

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Verhoogde leesbewerking voor administratief onderzoek (preview)

Met lezen met verhoogde bevoegdheden kan een geautoriseerde ontwikkelaar gelabelde documenten teruggeven die de aanroepende gebruiker normaal gesproken niet kan zien, waarbij voor elk document dat door de aanvraag wordt teruggegeven een Microsoft Purview-auditlogboekvermelding wordt vastgelegd. Gebruik dit voor nalevingsbeoordelingen, eDiscovery, incidentrespons en andere administratieve onderzoeken waarbij een controleerbare record van toegang is vereist.

Lezen met verhoogde bevoegdheid is beschikbaar voor indexen met Purview-functionaliteit in REST API-versie 2026-05-01-preview en hoger.

Hoe verhoogde leesacties werken

1. De aanroepende toepassing stelt de x-ms-enable-elevated-read: true header in op de zoekaanvraag.

2. Azure AI Zoeken slaat de toegangscontrole per document op basis van labels over en retourneert overeenkomende documenten, ongeacht de EXTRACT machtigingen van de gebruiker die een aanvraag indient.

3. Voor elk document in het antwoord verzendt Azure AI Zoeken één vermelding naar het Microsoft Purview auditlogboek namens de aanvragende tenant. Eén zoekaanvraag die N-documenten retourneert, produceert N controlevermeldingen.

4. Controlevermeldingen worden asynchroon geüpload naar Purview nadat het zoekantwoord is geretourneerd.

Vereiste roltoewijzing

De aanroepende ontwikkelaargebruiker moet over de rol Inzender van zoekindexgegevens beschikken op het niveau van de zoekservice of het bereik van de index. Search Index Data Reader is niet voldoende. Uitgebreide leesbewerking mislukt met 403 Forbidden als de rol niet is toegewezen. Zie Connect to Azure AI Zoeken using roles voor meer informatie over Azure AI Zoeken rollen.

Wanneer de x-ms-enable-elevated-read koptekst is ingesteld op true, mag de x-ms-query-source-authorization header niet worden gebruikt.

Voorbeeld van verhoogde leesbewerking

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{contributor-token}}
x-ms-enable-elevated-read: true
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Auditvelden die naar Microsoft Purview worden verzonden

Elke controlevermelding volgt het Office 365 management activity-API en bevat de volgende velden.

Gracieuze degradatie

Als Azure AI Zoeken geen Microsoft Purview kan bereiken tijdens het verwerken van een query, zoals tijdens een tijdelijke Purview-storing, wordt de labelevaluatie voor die aanvraag overgeslagen. Het gedrag is afhankelijk van of de aanvraag een gebruikersidentiteitstoken bevat:

• Leesaanvragen met verhoogde bevoegdheid (x-ms-enable-elevated-read: true): De aanvraag mislukt met 5xx. Azure AI Zoeken retourneert geen gelabelde documenten zonder eerst auditlogboeken te kunnen genereren.

• Standaard via labels afgedwongen verzoeken (met x-ms-query-source-authorization): Het verzoek mislukt met 5xx. Azure AI Zoeken retourneert geen gedeeltelijke of niet-gefilterde resultaten wanneer het labelbeleid niet kan evalueren.

• Oproepen zonder x-ms-query-source-authorization uitgegeven door een toepassing met ten minste de rol Search Index Data Reader : De aanvraag slaagt en retourneert alleen documenten die geen vertrouwelijkheidslabel hebben. Gelabelde documenten worden weggelaten uit het antwoord.

Dit gedegradeerde pad is alleen bedoeld voor niet-gebruikersgerichte werkstromen die expliciet niet-gelabelde resultaten accepteren. Vertrouw er niet op voor zoekervaringen voor eindgebruikers.

Voor de volledige lijst met foutcodes die worden geretourneerd bij de evaluatie van vertrouwelijkheidslabels tijdens de query, zie Queryfouten oplossen.

Auditlogboeken met verhoogde bevoegdheid zoeken in Microsoft Purview

Azure AI Zoeken auditvermeldingen uploadt naar het Microsoft Purview auditlogboek van de aanroepende tenant. Verhoogde leesactiviteit onderzoeken:

1. Selecteer in de Microsoft Purview-portalSolutions>Audit.

2. Selecteer Audit Search en filter op datumbereik, gebruiker of recordtype Azure AI Zoeken.

3. Open een vermelding om de standaardschemavelden en de aangepaste Azure AI Zoeken-velden weer te geven, waaronder SensitivityLabelName, DocumentDataSourceType en DocumentDataSourceId.

Zie Zoeken in het auditlogboek in de Microsoft Purview-portal voor stapsgewijze instructies voor het uitvoeren van zoekopdrachten, retentiegedrag en vereiste Purview-rollen.

Verwerking van vertrouwelijkheidslabels in Azure AI Zoeken

Wanneer Azure AI Zoeken documentinhoud indexeert met vertrouwelijkheidslabels uit bronnen zoals SharePoint, Azure Blob en andere, worden zowel de inhoud als de metagegevens van het label opgeslagen. De zoekquery retourneert geïndexeerde inhoud samen met de GUID die het vertrouwelijkheidslabel identificeert dat op het document is toegepast, alleen als de gebruiker gegevenstoegang EXTRACT heeft voor dat document dat is toegewezen via de definitie van het vertrouwelijkheidslabel. Deze GUID identificeert het label op unieke wijze, maar bevat geen eigenschappen die leesbaar zijn voor mensen, zoals de labelnaam of de bijbehorende machtigingen.

Houd er rekening mee dat de GUID alleen onvoldoende is voor scenario's met een gebruikersinterface, omdat vertrouwelijkheidslabels vaak andere beleidsbesturingselementen bevatten die worden afgedwongen door Microsoft Purview Informatiebeveiliging, zoals: afdrukmachtigingen of schermopnamebeperkingen. Azure AI Zoeken biedt deze mogelijkheden niet weer.

Als u labelnamen wilt weergeven en/of ui-specifieke beperkingen wilt afdwingen, moet uw toepassing het Microsoft Purview Informatiebeveiliging-eindpunt aanroepen om volledige labelmetagegevens en bijbehorende machtigingen op te halen.

U kunt de GUID die door Azure AI Zoeken wordt geretourneerd, gebruiken om de labeleigenschappen op te lossen en de Purview Labels API's aan te roepen om de labelnaam, beschrijving en beleidsinstellingen op te halen.

Problemen met queryfouten oplossen

Wanneer de evaluatie van vertrouwelijkheidslabels in querytijd mislukt, retourneert Azure AI Zoeken een specifieke HTTP-foutcode die de oorzaak identificeert. De service retourneert nooit een gedeeltelijke of ongefilterde resultatenset. Als labelbeleid niet kan worden geëvalueerd, mislukt de query in plaats van het weergeven van niet-gelabelde of niet-geautoriseerde inhoud.

400 Foute Verzoek

Een 400-fout geeft een probleem aan met de indexconfiguratie of de aanvraagheaders. Herstel de configuratie voordat u het opnieuw probeert.

401 Niet geautoriseerd

Een 401-fout geeft een probleem aan met het autorisatietoken of de Purview-machtigingen van de toepassing.

502 Bad Gateway

Een 502-fout geeft een verbindingsfout aan tussen Azure AI Zoeken en Microsoft Purview. Deze fouten zijn doorgaans tijdelijk.

Time-out van 504 gateway

Een 504-fout geeft aan dat Microsoft Purview niet binnen de toegestane tijd heeft gereageerd.

End-to-end-testopstelling

Raadpleeg de voorbeeld-end-to-end-configuratie om de configuratie van uw gevoeligheidslabel in Azure AI Zoeken te valideren.

In deze opslagplaats ziet u hoe u het volgende kunt doen:

• Synchronisatie en naleving van vertrouwelijkheidslabels configureren in Azure AI Zoeken
• Testscenario’s voor inname en afdwinging tijdens query’s voor documenten met vertrouwelijkheidslabels
• Pak de labelnaam uit en maak deze beschikbaar als onderdeel van de bronvermeldingen die worden gebruikt in uw RAG-toepassingen of -agents.