Frågetids-ACL och RBAC-tillämpning i Azure AI-sökning (förhandsversion)

Åtkomstkontroll för frågetid (förhandsversion) säkerställer att användarna endast hämtar sökresultat som de har behörighet att komma åt, baserat på deras identitet, gruppmedlemskap, roller eller attribut. Den här funktionen är viktig för säkra företagssökningar och efterlevnadsdrivna arbetsflöden.

Auktoriserad åtkomst beror på behörighetsmetadata som matas in under indexeringen. För indexerares datakällor som har inbyggda åtkomstmodeller, till exempel Azure Data Lake Storage (ADLS) Gen2 och SharePoint i Microsoft 365, kan en indexerare automatiskt hämta behörighetsmetadata för varje dokument. För andra datakällor måste du montera dokumentnyttolasten själv och nyttolasten måste innehålla både innehåll och associerade behörighetsmetadata. Sedan använder du push-API:erna för att läsa in indexet.

Den här artikeln beskriver hur du konfigurerar frågor som använder behörighetsmetadata för att filtrera resultat.

Förutsättningar

• Behörighetsmetadata måste finnas i filterable strängfält. Du kommer inte att använda filtret i dina frågor, men sökmotorn skapar ett filter internt för att undanta obehörigt innehåll.

• Behörighetsmetadata måste bestå av antingen POSIX-behörigheter som identifierar åtkomstnivån och grupp- eller användar-ID:t eller resurs-ID:t för containern i ADLS Gen2 om du använder RBAC-omfång.

• För ACL-baserat framtvingande med anpassat intag lagrar du userIds och groupIds som Microsoft Entra-objekt-ID:n (GUIDs) i filterbara fält. Vid frågetillfället matchar tjänsten identiteterna i x-ms-query-source-authorization mot de lagrade ID:n. Schemainformation finns i Indexera dokumentåtkomstkontrollistor (ACL:er) med hjälp av PUSH REST API:er (förhandsversion).

• Beroende på datakälla:

  • För ADLS Gen2-datakällor måste du ha konfigurerat åtkomstkontrollistor (ACL: er) och/eller Azure rollbaserade åtkomstkontrollroller (RBAC) på containernivå.
  • För Azure Blob-datakällor måste du ha rolltilldelningar i containern. Du kan använda en inbyggd indexerare, en kunskapskälla eller push-API:er för att indexera behörighetsmetadata i ditt index.
  • För SharePoint datakällor måste du konfigurera åtkomstkontrollistor (ACL). Du kan använda en built-in SharePoint indexerare och konfigurera den med ACL-inmatningsfunktioner. Du kan också använda en indexerad SharePoint kunskapskälla och konfigurera den för att framtvinga behörigheter på dokumentnivå. Gruppbaserade behörigheter, inklusive Microsoft 365-grupper, stöds när de matas in som Entra-objekt-ID:er. Expandering av grupper sker vid frågetillfället via Microsoft Graph.

• Använd den senaste förhandsversionen av REST API eller ett förhandsversionspaket för en Azure SDKs för att fråga indexet eller kunskapskällan. Den här API-versionen stöder interna frågor som filtrerar bort obehöriga resultat.

Begränsningar

• Om ACL-utvärderingen misslyckas (till exempel om Graph API inte är tillgänglig) returnerar tjänsten 5xx och not returnerar en delvis filtrerad resultatuppsättning.

• ACL-färskhet beror på inmatningsmetoden. För att undvika inaktuella auktoriseringsbeslut planerar du för hur varje källa sprider behörighetsändringar till indexet:

  • En schemalagd SharePoint indexeraren uppdaterar behörighetsändringar på objektnivå vid varje körning. Ändringar i ett överordnat omfång (webbplats, bibliotek, lista eller mapp) som ärvs av underordnade objekt kräver en omsynkronisering.
  • En ADLS Gen2-indexerare kräver en omsynkronisering för att uppdatera ACL:er.
  • Anpassad inmatning eller push-inmatning kräver att du återger de berörda dokumenten.

• Dokumentsynlighet kräver båda:

  • Det anropande programmets RBAC-roll (auktoriseringshuvud).
  • Användaridentiteten som bärs av x-ms-query-source-authorization.

• Inledande ACL-baserade frågor kan få högre svarstid jämfört med efterföljande begäranden på grund av kostnader för cachelagring och behörighetsmatchning.

• För indexerat SharePoint-innehåll expanderas inte en Microsoft Entra-grupp som är kapslad i en SharePoint-grupp. Microsoft Entra-transitiv gruppupplösning stöder inte den här blandade relationen. Se Grupprelationer som stöds.

ACL-inmatningsgränser per datakälla

Gränser för inlägg i åtkomstkontrollistor (ACL) definierar hur många distinkta behörighetsposter som kan knytas till en fil, mapp eller ett objekt i en ansluten datakälla. Varje post representerar en enskild användar- eller gruppidentitet och de åtkomsträttigheter som beviljas till den identiteten (till exempel Läsa, Skriva eller Kör).

Det maximala antalet ACL-poster som stöds av Azure AI-sökning funktioner varierar beroende på datakällans typ:

Azure Data Lake Storage Gen2 (ADLS Gen2): Varje fil eller katalog kan ha behörigheter för upp till 32 ACL. I det här sammanhanget innebär en postering en enskild huvudaktör (användare eller grupp) med en specifik behörighetsuppsättning. Exempel: Att tilldela läsåtkomst för "Alla" och körrättigheter för "Azure-användare" skulle räknas som två ACL-poster.

SharePoint i Microsoft 365: SharePoint-datakälla i sökresultat stöder upp till 1 000 behörighetsposter per dokument. Varje post representerar en unik användar- eller grupptilldelning i objektets behörighetslista. Detta skiljer sig från de övergripande gränserna för unika behörighetsomfattningar per lista eller bibliotek, som styr hur många objekt som kan ha unika behörigheter.

De här gränserna avgör hur detaljerad Azure AI-sökning kan uppfylla behörigheter på objektnivå vid indexering eller filtrering av sökresultat. Om ett objekt överskrider dessa ACL-inmatningsgränser kan det hända att behörigheter som överskrider gränsen inte tillämpas vid frågetillfället.

Så här fungerar frågetidsframtvingande

I det här avsnittet listas ordningen för ACL-tillämpning vid frågetillfället. Åtgärderna varierar beroende på om du använder Azure RBAC-omfång eller Microsoft Entra ID grupp- eller användar-ID.

1. Indata för användarbehörigheter

Slutanvändarprogrammet innehåller en frågeåtkomsttoken som en del av sökfrågebegäran och den åtkomsttoken är vanligtvis användarens identitet. I följande tabell visas källan till de användarbehörigheter som stöds av Azure AI-sökning för ACL-tillämpning:

2. Konstruktion av säkerhetsfilter

Internt skapar Azure AI-sökning dynamiskt säkerhetsfilter baserat på de användarbehörigheter som tillhandahålls. Dessa säkerhetsfilter läggs automatiskt till i alla filter som kan komma in med frågan om indexet har alternativet för behörighetsfilter aktiverat.

För Azure RBAC är behörigheter listor över resurs-ID-strängar. Det måste finnas en Azure-rolltilldelning (Storage Blob Data Reader) som på datakällan ger åtkomst till säkerhetsprincipalen token i auktoriseringshuvudet. Filtret exkluderar dokument om det inte finns någon rolltilldelning för principen bakom åtkomsttoken i begäran.

3. Resultatfiltrering

Säkerhetsfiltret matchar effektivt userIds, groupIds och rbacScope från begäran mot varje lista med ACL:er i varje dokument i sökindexet för att begränsa de resultat som returneras till dem som användaren har åtkomst till. Det är viktigt att observera att varje filter tillämpas oberoende av varandra och att ett dokument anses ha behörighet om något filter lyckas. Om en användare till exempel har åtkomst till ett dokument via userIds men inte via groupIds anses dokumentet fortfarande vara giltigt och returneras till användaren.

SharePoint grupper vid frågetillfället

Från och med REST API för förhandsversionen 2026-05-01 kan Azure AI-sökning respektera SharePoint medlemskap i webbplatsgrupper, till exempel Ägare, Medlemmar, Besökare och anpassade webbplatsgrupper, vid frågetillfället. För att aktivera det här scenariot måste indexet innehålla:

• En egenskap sharePointConnectorAppRegistration som refererar till den federerade identitetsautentiseringsuppgiften för det Microsoft Entra program som används för att anropa SharePoint för användarens räkning.
• Ett fält markerat med attributet sharepointSiteUrl: true som lagrar SharePoint webbplats-URL:en för varje indexerat objekt (kallas vanligtvis SharePointSiteUrl och fylls i från källfältet metadata_spo_site_url).

Vid tidpunkten för frågan använder Azure AI-sökning den registrerade applikationen och webbplatsens URL för varje kandidatdokument för att fastställa den anropande användarens medlemskap i SharePoint-grupper på den webbplatsen. De lösta grupperna matchas mot de spg:prefixvärden som lagras i groupIds fältet för behörighetsfilter. Prefixet spg: särskiljer SharePoint-webbplatsgrupper från objekt-ID:n för Microsoft Entra-grupper, som lagras utan prefixet.

Information om konfiguration och begränsningar finns i Konfigurera stöd för SharePoint-grupper.

Om SharePoint behörighetsfiltrering returnerar saknade eller oväntade resultat kan du läsa Felsöka SharePoint behörighetsfiltrering.

Exempel: Fråga med tillämpning av SharePoint-webbplatsgrupp

Begäran är identisk med den ACL-framtvingade standardfrågan. Söktjänsten använder indexets sharePointConnectorAppRegistration för att fastställa SharePoint-gruppmedlemskap åt anroparen. Inkludera GroupIds i satsen select för att se värden med prefixet spg: i svaret.

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

Frågeexempel

Här är ett exempel på en frågebegäran från samplingskod. Frågetoken är en Microsoft Entra åtkomsttoken för den frågande användaren.

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

Utökade behörigheter för att undersöka felaktiga resultat (förhandsversion)

Felsökning av frågor som innehåller behörighetsmetadata kan vara problematiskt eftersom sökresultaten är specifika för varje användare. Som utvecklare eller administratör kan du behöva utökade behörigheter för att returnera resultat oavsett behörighetsmetadata så att du kan undersöka problem med frågor som returnerar obehörigt innehåll.

För att undersöka måste du kunna:

• Visa den uppsättning dokument som slutanvändaren kan visa baserat på användarens behörigheter.

• Visa alla dokument i indexet för att undersöka varför vissa kanske inte är synliga för slutanvändaren.

Du kan utföra dessa uppgifter genom att lägga till ett anpassat huvud, x-ms-enable-elevated-read: true, i en fråga.

Behörigheter för begäranden med utökade läsbehörigheter

Du måste ha behörigheter för Search Index Data Contributor eller en anpassad roll som innehåller behörigheten Elevate Read.

Förfrågningar är en åtgärd på dataplanet, så den anpassade rollen kan endast bestå av atomiska behörigheter på dataplanet. Lägg till behörigheten Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read för en anpassad roll.

Lägga till en upphöjd läsrubrik i en fråga

När du har konfigurerat behörigheter kan du köra frågan. Följande exempel är en frågebegäran mot ett sökindex.

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
}

Viktiga beteendeändringar för ACL-funktioner i specifika förhandsversioner av API:et

Före REST API-versionen 2025-11-01-preview, tidigare förhandsversioner 2025-05-01-preview och 2025-08-01-preview returnerade alla dokument när du använder en tjänst-API-nyckel eller auktoriserade Entra-roller, även om ingen användartoken angavs. Program som inte verifierade förekomsten av en användartoken kan oavsiktligt exponera resultat för slutanvändare om de inte implementeras korrekt eller enligt bästa praxis.

Från och med november 2025 ändrades det här beteendet:

• ACL-behörighetsfilter gäller nu även om du endast använder tjänst-API-nycklar eller Entra-autentisering i alla versioner som stöder ACL.
• Om användartoken utelämnas returneras inte ACL-skyddat innehåll.
• Om du vill visa alla dokument för felsökning måste du uttryckligen inkludera rubriken för upphöjd läsning när du använder REST API-versionen 2026-05-01-preview eller senare.

Den här uppdateringen hjälper till att skydda innehåll när program inte tillämpar metodtips för tokenverifiering.

Relaterat innehåll

• Självstudie: Indexering av behörighetsmetadata från ADLS Gen2 och fråga med behörighetsfiltrerade resultat (förhandsversion)
• Indexera dokumentåtkomstkontrollistor (ACL: er) med hjälp av PUSH REST API:er (förhandsversion)
• Använd en ADLS Gen2-indexerare för att mata in behörighetsmetadata och filtrera sökresultat baserat på användaråtkomsträttigheter (förhandsversion)
• Använda en blobindexerare eller kunskapskälla för att mata in METADATA för RBAC-omfång
• Använd en SharePoint indexerare för att mata in behörighetsmetadata och filtrera sökresultat baserat på användaråtkomsträttigheter (förhandsversion)