ACL- és RBAC-érvényesítés lekérdezéskor az Azure AI Keresésben (előzetes verzió)

A lekérdezési idő hozzáférés-vezérlése (előzetes verzió) biztosítja, hogy a felhasználók csak az identitásuk, csoporttagságuk, szerepköreik vagy attribútumaik alapján kérjék le a hozzáférésre jogosult keresési eredményeket. Ez a funkció elengedhetetlen a biztonságos vállalati keresési és megfelelőségi alapú munkafolyamatokhoz.

Az engedélyezett hozzáférés az indexelés során betöltött engedély metaadataitól függ. Olyan indexelő adatforrások esetében, amelyek beépített hozzáférési modellekkel rendelkeznek, például Azure Data Lake Storage (ADLS) Gen2 és SharePoint Microsoft 365, az indexelők automatikusan lekérhetik az egyes dokumentumok engedély metaadatait. Más adatforrások esetében saját magának kell összeállítania a dokumentumcsomagot, amelynek tartalmaznia kell mind a tartalmat, mind a kapcsolódó engedélyek metaadatait. Ezután a leküldéses API-k használatával töltheti be az indexet.

Ez a cikk bemutatja, hogyan állíthat be olyan lekérdezéseket, amelyek jogosultsági metaadatokat használnak az eredmények szűréséhez.

Előfeltételek

• Az engedély metaadatainak filterable karakterlánc mezőkben kell lenniük. A szűrőt nem fogja használni a lekérdezésekben, de a keresőmotor belső szűrőt hoz létre a jogosulatlan tartalmak kizárásához.

• Az engedély metaadatainak POSIX-stílusú engedélyekből kell állniuk, amelyek azonosítják a hozzáférési szintet és a csoport- vagy felhasználói azonosítót, vagy az ADLS Gen2 tárolójának erőforrás-azonosítóját, ha RBAC-hatókört használ.

• Egyéni betöltés használata esetén az ACL-alapú érvényesítéshez tárolja a(z) userIds és groupIds értékeket Microsoft Entra objektumazonosítóként (GUID-ként) szűrhető mezőkben. Lekérdezéskor a szolgáltatás összeveti a(z) x-ms-query-source-authorization elemben található identitásokat a tárolt azonosítókkal. A séma részleteiért lásd: Dokumentumhozzáférés-vezérlési listák (ACL-ek) indexelése a leküldéses REST API-k (előzetes verzió) használatával.

• Az adatforrástól függően:

  • Az ADLS Gen2-adatforrások esetében konfigurált hozzáférés-vezérlési listákkal (ACL-ekkel) és/vagy Azure szerepköralapú hozzáférés-vezérlési (RBAC) szerepkörrel kell rendelkeznie a tároló szintjén.
  • A Azure Blob-adatforrások esetében szerepkör-hozzárendelésekkel kell rendelkeznie a tárolón. A beépített indexelő, a tudásbázis vagy a Push API-k használatával indexelheti az engedély metaadatait az indexben.
  • SharePoint adatforrásokhoz hozzáférés-vezérlési listákat (ACL-eket) kell konfigurálnia. Használhat egy built-in SharePoint indexelőt és konfigurálhatja ACL betöltési képességekkel. Indexelt SharePoint tudásbázist is használhat, és konfigurálhatja a dokumentumszintű engedélyek kikényszerítéséhez. A csoportalapú engedélyek, beleértve a Microsoft 365-csoportok, akkor támogatottak, ha Entra-objektumazonosítókként vannak betöltve. A csoportbővítés lekérdezési időben történik Microsoft Graph keresztül.

• Az index vagy a tudásbázis lekérdezéséhez használja a latest preview REST API vagy egy Azure SDK előnézeti csomagját. Ez az API-verzió olyan belső lekérdezéseket támogat, amelyek kiszűrik a jogosulatlan eredményeket.

Korlátozások

• Ha az ACL-kiértékelés sikertelen (például a Graph API nem érhető el), a szolgáltatás 5xx ad vissza, és not részben szűrt eredményhalmazt ad vissza.

• Az ACL frissessége a betöltés módjától függ. Az elavult engedélyezési döntések elkerülése érdekében tervezze meg, hogy az egyes források hogyan propagálják az engedélymódosításokat az indexben:

  • Az ütemezett SharePoint indexelő minden futtatáskor frissíti az elemek szintjén történt engedélymódosításokat. A felsőbb szintű hatókör (webhely, dokumentumtár, lista vagy mappa) azon módosításai, amelyeket a gyermekelemek örökölnek, újraszinkronizálást igényelnek.
  • Az ADLS Gen2-indexelőknek újraszinkronizálásra van szükség az ACL-ek frissítéséhez.
  • Az egyéni vagy push alapú adatbetöltéshez újra be kell töltenie az érintett dokumentumokat.

• A dokumentum láthatóságához mindkettő szükséges:

  • A hívó alkalmazás RBAC-szerepköre (engedélyezési fejléc).
  • Az x-ms-query-source-authorization által hordozott felhasználói identitás.

• A kezdeti ACL-alapú lekérdezések nagyobb késést tapasztalhatnak a későbbi kérésekhez képest a gyorsítótárazás és az engedélyfeloldási többletterhelés miatt.

• A SharePointban indexelt tartalom esetén a SharePoint-csoporton belül beágyazott Microsoft Entra-csoport nem lesz kiterjesztve. A Microsoft Entra tranzitív csoportfeloldása nem támogatja ezt a vegyes típusú kapcsolatot. Lásd : Támogatott csoportkapcsolatok.

ACL-belépési korlátok adatforrásonként

A hozzáférés-vezérlési lista (ACL) belépési korlátai határozzák meg, hogy hány különböző engedélyrekord társítható egy fájlhoz, mappához vagy elemhez egy csatlakoztatott adatforráson belül. Minden bejegyzés egyetlen felhasználó vagy csoport identitását, valamint az adott identitáshoz biztosított hozzáférési jogosultságokat (például Olvasás, Írás vagy Végrehajtás) jelöli.

A Azure AI Keresés funkció által támogatott ACL-bejegyzések maximális száma az adatforrás típusától függően változik:

Azure Data Lake Storage Gen2 (ADLS Gen2): Minden fájl vagy könyvtár legfeljebb 32 ACL-bejegyzés engedélyekkel rendelkezhet. Ebben a kontextusban a bejegyzés egyetlen entitást (felhasználót vagy csoportot) jelent egy meghatározott engedélykészlettel. Példa: a "Mindenki" olvasási hozzáférés és a "Azure felhasználók" végrehajtási hozzáférés hozzárendelése két ACL-bejegyzésnek számít.

SharePoint a Microsoft 365: SharePoint keresési adatforrás fájlonként legfeljebb 1000 engedélybejegyzést támogat. Minden bejegyzés egy egyedi felhasználó- vagy csoport-hozzárendelést jelöl az elem engedélylistájában. Ez különbözik a listák vagy tárak általános egyedi engedélyhatókör-korlátaitól , amely azt szabályozza, hogy hány elem rendelkezhet egyedi engedélyekkel.

Ezek a korlátok határozzák meg, hogy az Azure AI Keresés rendszer mennyire képes tiszteletben tartani az elemszintű engedélyt a keresési eredmények indexelése vagy szűrése során. Ha egy elem túllépi ezeket az ACL-belépési korlátokat, előfordulhat, hogy a korláton túli engedélyek nem lesznek kényszerítve a lekérdezési időpontban.

Hogyan működik a lekérdezés közbeni érvényesítés

Ez a szakasz az ACL-kényszerítés műveleteinek sorrendjét sorolja fel a lekérdezési időpontban. A műveletek attól függően változnak, hogy Azure RBAC-hatókört vagy Microsoft Entra ID csoport- vagy felhasználói azonosítókat használ.

1. Felhasználói engedélyek bemenete

A végfelhasználói alkalmazás a keresési lekérdezési kérelem részeként tartalmaz egy lekérdezési hozzáférési jogkivonatot, és ez a hozzáférési jogkivonat általában a felhasználó identitása. Az alábbi táblázat az ACL-kényszerítés Azure AI Keresés által támogatott felhasználói engedélyek forrását sorolja fel:

2. Biztonsági szűrő felépítése

Belsőleg Azure AI Keresés a megadott felhasználói engedélyek alapján dinamikusan hozza létre a biztonsági szűrőket. A rendszer automatikusan hozzáfűzi ezeket a biztonsági szűrőket a lekérdezéshez esetlegesen érkező szűrőkhöz, ha az indexen engedélyezve van az engedélyszűrő beállítás.

Az RBAC Azure esetében az engedélyek az erőforrás-azonosító sztringjeinek listájai. Az adatforráson egy Azure szerepkör-hozzárendelésnek (Storage Blob Data Reader) kell lennie, amely hozzáférést biztosít a biztonsági főtétel tokenhez az engedélyezési fejlécben. A szűrő kizárja a dokumentumokat, ha a kérelem hozzáférési tokenje mögött nincs szerepkör-hozzárendelés.

3. Eredmények szűrése

A biztonsági szűrő hatékonyan összeveti a kérésben szereplő userId-eket, groupId-eket és rbacScope-okat a keresési index minden dokumentumában található ACL-listák mindegyikével, hogy a felhasználó által hozzáférhető találatokat korlátozza. Fontos megjegyezni, hogy a rendszer minden szűrőt egymástól függetlenül alkalmaz, és egy dokumentum akkor minősül engedélyezettnek, ha egy szűrő sikeres. Ha például egy felhasználó a userId-eken keresztül fér hozzá egy dokumentumhoz, de nem csoportazonosítókon keresztül, akkor a dokumentum továbbra is érvényesnek minősül, és visszakerül a felhasználóhoz.

SharePoint csoportok lekérdezéskor

A 2026-05-01-preview REST API-tól kezdve az Azure AI Keresés lekérdezési időben figyelembe tudja venni a SharePoint-webhelycsoportokban fennálló tagságot, például a Tulajdonosok, a Tagok, a Látogatók és az egyéni webhelycsoportok esetében. A forgatókönyv engedélyezéséhez az indexnek tartalmaznia kell a következőket:

• Egy sharePointConnectorAppRegistration tulajdonság, amely a felhasználó nevében SharePoint hívásához használt Microsoft Entra alkalmazás összevont identitás-hitelesítő adataira hivatkozik.
• Az a sharepointSiteUrl: true attribútummal jelölt mező, amely az egyes indexelt elemekhez tartozó SharePoint-webhely URL-címét tárolja (jellemzően SharePointSiteUrl nevű, és a metadata_spo_site_url forrásmezőből van feltöltve).

Lekérdezéskor Azure AI Keresés a regisztrált alkalmazást és a webhely URL-címét használja az egyes jelölt dokumentumokon a hívó felhasználó SharePoint-csoport tagságának feloldásához. A feloldott csoportok megegyeznek az spg:engedélyszűrő mezőben tárolt groupIds -előtagú értékekkel. A spg: előtag megkülönbözteti SharePoint helycsoportokat Microsoft Entra csoportobjektum-azonosítóktól, amelyek előtag nélkül vannak tárolva.

A konfiguráció részleteiről és korlátozásáról a Konfigurálási SharePoint csoportok támogatása című témakörben olvashat.

Ha SharePoint engedélyszűrés hiányzó vagy váratlan eredményeket ad vissza, tekintse meg SharePoint engedélyszűrés hibaelhárítását.

Példa: Lekérdezés a SharePoint webhelycsoport érvényesítésével

A kérés megegyezik a szabványos ACL által kikényszerített lekérdezéssel. A keresési szolgáltatás az index sharePointConnectorAppRegistration elemét használja a SharePoint-csoporttagság feloldásához a hívó fél nevében. Foglalja bele a(z) GroupIds elemet a(z) select záradékba, hogy a válaszban láthassa az spg: előtagú értékeket.

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

Lekérdezés példa

Íme egy példa egy lekérési kérelemre a mintakódból. A lekérdezési jogkivonat egy Microsoft Entra hozzáférési jogkivonat a lekérdezést végző felhasználó számára.

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

Emelt szintű engedélyek a helytelen eredmények vizsgálatához (előzetes verzió)

Az engedély metaadatait tartalmazó lekérdezések hibakeresése problémás lehet, mivel a keresési eredmények minden felhasználóra vonatkoznak. Fejlesztőként vagy rendszergazdaként előfordulhat, hogy emelt szintű engedélyekre van szüksége az eredmények visszaadásához az engedély metaadataitól függetlenül, hogy kivizsgálhassa a jogosulatlan tartalmakat visszaküldött lekérdezésekkel kapcsolatos problémákat.

A vizsgálathoz képesnek kell lennie a következőre:

• Megtekintheti azokat a dokumentumokat, amelyeket a végfelhasználó az adott felhasználó engedélyei alapján meg tud tekinteni.

• Tekintse meg az index összes dokumentumát annak vizsgálatához, hogy egyes dokumentumok miért nem láthatók a végfelhasználó számára.

Ezeket a feladatokat úgy hajthatja végre, x-ms-enable-elevated-read: truehogy hozzáad egy egyéni fejlécet egy lekérdezéshez.

Emelt szintű olvasási kérelmek engedélyei

Keresési index adat-hozzáférési engedélyekkel vagy olyan egyéni szerepkörrel kell rendelkeznie, amely tartalmazza az Kiemelt olvasási engedélyt.

A lekérdezések adatsík-műveletek, így az egyéni szerepkör csak atomi adatsík-engedélyekből állhat. Egyéni szerepkör esetén adja hozzá a Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read engedélyt.

Kiemelt olvasási fejléc hozzáadása lekérdezéshez

Az engedélyek beállítása után futtathatja a lekérdezést. Az alábbi példa egy keresési index lekérdezési kérése.

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
}

Fontos ACL-funkciók viselkedésének módosítása az előzetes verziójú API-verziókban

A REST API-verzió 2025-11-01-preview előtt a korábbi előzetes verziók 2025-05-01-preview és 2025-08-01-preview minden dokumentumot visszaadtak szolgáltatás API-kulcs vagy engedélyezett Entra-szerepkör használata esetén, még akkor is, ha nem állt rendelkezésre felhasználói jogkivonat. Azok az alkalmazások, amelyek nem ellenőrizték a felhasználói jogkivonat meglétét, véletlenül elérhetővé tehetik az eredményeket a végfelhasználók számára, ha nincsenek megfelelően implementálva, vagy követik az ajánlott eljárásokat.

2025 novemberétől ez a viselkedés megváltozott:

• Az ACL-engedélyszűrők mostantól akkor is érvényesek, ha csak szolgáltatás API-kulcsokat vagy Entra-hitelesítést használnak az ACL-t támogató összes verzióban.
• Ha a felhasználói jogkivonat nincs megadva, a rendszer nem ad vissza ACL által védett tartalmat.
• A hibaelhárításhoz szükséges összes dokumentum megtekintéséhez a(z) 2026-05-01-preview vagy újabb REST API-verzió használatakor explicit módon meg kell adnia az emelt szintű olvasási fejlécet.

Ez a frissítés segít a tartalom védelmében, ha az alkalmazások nem kényszerítik ki a jogkivonatok érvényesítésére vonatkozó ajánlott eljárásokat.

Kapcsolódó tartalom

• Oktatóanyag: Engedély metaadatainak indexelése az ADLS Gen2-ből és lekérdezés engedélyszűréssel (előzetes verzió)
• Dokumentumhozzáférés-vezérlési listák (ACL-ek) indexelése a leküldéses REST API-k használatával (előzetes verzió)
• ADLS Gen2-indexelő használata jogosultsági metaadatok betöltésére és keresési eredmények szűrésére felhasználói hozzáférési jogosultságok (előzetes verzió) alapján
• Az RBAC-hatókörök metaadatainak betöltése blobindexelő vagy tudásbázis használatával
• SharePoint indexelő használata jogosultsági metaadatok betöltéséhez és keresési eredmények szűréséhez felhasználói hozzáférési jogosultságok (előzetes verzió) alapján