Vynucování ACL a řízení přístupu na základě rolí při zpracování dotazu ve službě Azure AI Vyhledávač (preview)

Řízení přístupu v době dotazu (Preview) zajišťuje, že uživatelé načítají jenom výsledky hledání, ke kterým mají oprávnění přistupovat, a to na základě jejich identity, členství ve skupinách, rolích nebo atributech. Tato funkce je nezbytná pro zabezpečené podnikové vyhledávání a pracovní postupy řízené dodržováním předpisů.

Autorizovaný přístup závisí na metadatech oprávnění, která se ingestují během indexování. U zdrojů dat indexeru, které mají integrované přístupové modely, jako jsou Azure Data Lake Storage (ADLS) Gen2 a SharePoint v Microsoft 365, může indexer automaticky načíst metadata oprávnění pro každý dokument. U jiných zdrojů dat musíte datovou část dokumentu sestavit sami a datová část musí obsahovat obsah i přidružená metadata oprávnění. Poté použijete push API k načtení indexu.

Tento článek vysvětluje, jak nastavit dotazy, které k filtrování výsledků používají metadata oprávnění.

Požadavky

• Metadata oprávnění musí být v filterable řetězcových polích. Filtr nebudete ve svých dotazech používat, ale vyhledávací web interně vytvoří filtr, který vyloučí neautorizovaný obsah.

• Metadata oprávnění se musí skládat z oprávnění stylu POSIX, která identifikují úroveň přístupu a ID skupiny nebo uživatele, nebo ID prostředku kontejneru v ADLS Gen2, pokud používáte obor RBAC.

• Pro vynucování na základě seznamů ACL s vlastním ingestováním dat ukládejte userIds a groupIds jako ID objektů Microsoft Entra (GUID) do filtrovatelných polí. Při dotazu služba porovnává identity v x-ms-query-source-authorization s těmito uloženými ID. Podrobnosti o schématu najdete v tématu Indexování seznamů řízení přístupu k dokumentům (ACL) pomocí nabízených rozhraní REST API (Preview).

• V závislosti na zdroji dat:

  • U zdrojů dat ADLS Gen2 musíte mít nakonfigurované seznamy řízení přístupu (ACLs) a/nebo Azure role založené na řízení přístupu (RBAC) na úrovni kontejneru.
  • Pro zdroje dat Azure Blob musíte mít přiřazení rolí v kontejneru. K indexování metadat oprávnění ve vašem indexu můžete použít integrovaný indexer, zdroj znalostí nebo Push API.
  • U SharePoint zdrojů dat je nutné nakonfigurovat seznamy řízení přístupu (ACL). Můžete použít vestavěný SharePoint indexátor a nakonfigurovat ho pomocí schopností příjmu ACL. Můžete také použít indexovaný SharePoint zdroj znalostí a nakonfigurovat ho tak, aby vynucoval oprávnění na úrovni dokumentu. Oprávnění založená na skupinách, včetně Skupin Microsoftu 365, jsou podporována při načtení jako ID objektů Entra. Rozšíření skupiny probíhá v době dotazu prostřednictvím Microsoft Graph.

• K dotazování indexu nebo zdroje znalostí použijte nejnovější verzi náhledu REST API nebo balíček náhledu Azure SDK. Tato verze rozhraní API podporuje interní dotazy, které odfiltrují neoprávněné výsledky.

Omezení

• Pokud se vyhodnocení seznamu ACL nezdaří (například Graph API není k dispozici), vrátí služba 5xx a nevrátí částečně filtrovanou sadu výsledků.

• Aktuálnost seznamu ACL závisí na metodě příjmu dat. Abyste se vyhnuli zastaralým rozhodnutím o autorizaci, naplánujte, jak každý zdroj rozšíří změny oprávnění do indexu:

  • Naplánovaný indexer SharePointu při každém spuštění aktualizuje změny oprávnění na úrovni položek. Změny v nadřazeném rozsahu (webu, knihovně, seznamu nebo složce), které jsou děděny podřízenými položkami, vyžadují opětovnou synchronizaci.
  • Indexer ADLS Gen2 vyžaduje opětovnou synchronizaci pro aktualizaci seznamů ACL.
  • Vlastní ingestování nebo push ingestion vyžaduje, abyste znovu ingestovali dotčené dokumenty.

• Viditelnost dokumentu vyžaduje obojí:

  • Role RBAC volající aplikace (autorizační hlavička).
  • Identita uživatele přenášená pomocí x-ms-query-source-authorization.

• Počáteční dotazy založené na ACL mohou mít vyšší latenci než následné požadavky kvůli režii spojené s ukládáním do mezipaměti a vyhodnocováním oprávnění.

• U indexovaného obsahu SharePointu se skupina Microsoft Entra vnořená do skupiny SharePointu nerozbalí. Microsoft Entra přechodné řešení skupin nepodporuje tento smíšený vztah. Viz Podporované relace skupin.

Omezení počtu položek ACL na zdroj dat

Omezení zadávání seznamu řízení přístupu (ACL) definují, kolik jedinečných záznamů oprávnění lze přidružit k souboru, složce nebo položce v připojeném zdroji dat. Každá položka představuje jednu identitu uživatele nebo skupiny a přístupová práva udělená této identitě (například čtení, zápis nebo spuštění).

Maximální počet položek seznamu ACL podporovaných funkcí Azure AI Vyhledávač se liší v závislosti na typu zdroje dat:

Azure Data Lake Storage Gen2 (ADLS Gen2): Každý soubor nebo adresář můžou mít oprávnění až 32 položek seznamu ACL. V tomto kontextu položka znamená jednoho hlavního uživatele nebo skupinu s konkrétní sadou oprávnění. Příklad: Přiřazení přístupu ke čtení „Všichni“ a „Azure uživatelé“ by se počítalo jako dvě položky seznamu řízení přístupu (ACL).

SharePoint v Microsoft 365: SharePoint zdroj dat ve vyhledávání podporuje až 1 000 položek oprávnění na soubor. Každá položka představuje jedinečné přiřazení uživatele nebo skupiny v seznamu oprávnění položky. To se liší od celkového omezení rozsahů jedinečných oprávnění na seznam nebo knihovnu, což určuje, kolik položek může mít jedinečná oprávnění.

Tato omezení určují, jak podrobná Azure AI Vyhledávač může respektovat oprávnění na úrovni položek při indexování nebo filtrování výsledků hledání. Pokud položka překročí tyto limity záznamů ACL, oprávnění přesahující tento limit se při zpracování dotazu nemusí vynucovat.

Jak funguje vynucení času dotazu

Tato sekce uvádí postup operací pro prosazování ACL při provádění dotazu. Operace se liší v závislosti na tom, jestli používáte rozsah Azure RBAC nebo Microsoft Entra ID pro skupiny nebo uživatele.

1. Vstup uživatelských oprávnění

Aplikace koncového uživatele zahrnuje přístupový token dotazu jako součást požadavku vyhledávacího dotazu a tento přístupový token je obvykle identita uživatele. Následující tabulka uvádí zdroj uživatelských oprávnění podporovaných Azure AI Vyhledávač pro vynucení seznamu ACL:

2. Konstrukce filtru zabezpečení

Interně Azure AI Vyhledávač dynamicky vytváří filtry zabezpečení na základě poskytnutých uživatelských oprávnění. Tyto filtry zabezpečení se automaticky připojí k jakýmkoli filtrům, které můžou být součástí dotazu, pokud má index povolenou možnost filtru oprávnění.

U Azure RBAC jsou oprávnění seznamy řetězců identifikátorů prostředků. Musí existovat přiřazení role Azure (Čtenář dat úložiště Blob) ve zdroji dat, které uděluje přístup k tokenu hlavního objektu zabezpečení v autorizační hlavičce. Filtr vyloučí dokumenty, pokud v požadavku neexistuje žádné přiřazení role objektu zabezpečení za přístupovým tokenem.

3. Filtrování výsledků

Filtr zabezpečení efektivně odpovídá identifikátorům userId, groupIds a rbacScope z požadavku na každý seznam ACL v každém dokumentu v indexu vyhledávání, aby byly vráceny pouze ty výsledky, ke kterým má uživatel přístup. Je důležité si uvědomit, že každý filtr se použije nezávisle a dokument se považuje za autorizovaný, pokud nějaký filtr proběhne úspěšně. Pokud má například uživatel přístup k dokumentu prostřednictvím id uživatele, ale ne prostřednictvím id skupiny, považuje se dokument za platný a vrátí se uživateli.

Skupiny SharePointu v době dotazu

Počínaje rozhraním REST API verze 2026-05-01-preview může Azure AI Vyhledávač respektovat členství ve skupinách webů SharePoint, jako jsou vlastníci, členové, návštěvníci a vlastní skupiny webů v době dotazu. Pokud chcete tento scénář povolit, musí index obsahovat:

• Vlastnost sharePointConnectorAppRegistration, která odkazuje na přihlašovací údaje federované identity aplikace Microsoft Entra používané k volání SharePoint jménem uživatele.
• Pole označené atributem sharepointSiteUrl: true, který ukládá adresu URL webu SharePoint pro každou indexovanou položku (obvykle s názvem SharePointSiteUrl a vyplněnou ze zdrojového pole metadata_spo_site_url).

Při zpracování dotazu Azure AI Vyhledávač používá zaregistrovanou aplikaci a adresu URL webu v každém kandidátním dokumentu k určení členství volajícího uživatele ve skupinách SharePointu na tomto webu. Vyhodnocené skupiny se porovnávají s hodnotami s předponou spg:, uloženými v poli filtru oprávnění groupIds. Předpona spg: rozlišuje SharePoint skupiny webů od ID objektů skupiny Microsoft Entra, které jsou uloženy bez předpony.

Podrobnosti o konfiguraci a omezeních najdete v tématu Konfigurace podpory skupin SharePointu.

Pokud SharePoint filtrování oprávnění vrací chybějící nebo neočekávané výsledky, přečtěte si téma Řešení potíží s filtrováním oprávnění SharePoint.

Příklad: Dotaz s vynucením skupiny webu SharePoint

Požadavek je stejný jako standardní dotaz vynucený seznamem ACL. Vyhledávací služba používá sharePointConnectorAppRegistration indexu k určení členství ve skupině SharePointu za volajícího. Zahrňte GroupIds do klauzule select, aby se v odpovědi zobrazily hodnoty s předponou spg:.

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

Příklad dotazu

Tady je příklad dotazu z ukázkového kódu. Token dotazu je přístupový token Microsoft Entra pro dotazujícího se uživatele.

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

Zvýšená oprávnění pro vyšetřování nesprávných výsledků (verze Preview)

Ladění dotazů, které obsahují metadata oprávnění, může být problematické, protože výsledky hledání jsou specifické pro každého uživatele. Jako vývojář nebo správce můžete potřebovat zvýšená oprávnění k vrácení výsledků bez ohledu na metadata oprávnění, abyste mohli zkoumat problémy s dotazy vracejícími neoprávněný obsah.

Abyste mohli prošetřit, musíte být schopni:

• Umožňuje zobrazit sadu dokumentů, které může koncový uživatel zobrazit na základě oprávnění daného uživatele.

• Zobrazte všechny dokumenty v indexu a prozkoumejte, proč některé dokumenty nemusí být viditelné pro koncového uživatele.

Tyto úlohy můžete provést přidáním vlastní hlavičky x-ms-enable-elevated-read: truedo dotazu.

Oprávnění pro žádosti se zvýšenými oprávněními ke čtení

Musíte mít oprávnění Přispěvatel dat indexu vyhledávání nebo vlastní roli, která zahrnuje oprávnění Elevate Read.

Dotazy jsou operace roviny dat, takže vlastní role se může skládat pouze z oprávnění atomické roviny dat. Pro vlastní roli přidejte oprávnění Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read.

Přidání hlavičky se zvýšenými oprávněními ke čtení do dotazu

Po nastavení oprávnění můžete dotaz spustit. Následující příklad je požadavek dotazu na index vyhledávání.

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
}

Změna důležitého chování funkce ACL v konkrétních verzích rozhraní API v náhledu

Před verzí REST API 2025-11-01-preview, starší verze Preview 2025-05-01-preview a 2025-08-01-preview vracely všechny dokumenty při použití klíče rozhraní API služby nebo autorizovaných rolí Entra, i když nebyl poskytnut žádný uživatelský token. Aplikace, které neověřily přítomnost tokenu uživatele, by mohly neúmyslně vystavit výsledky koncovým uživatelům, pokud nejsou správně implementované nebo dodržují osvědčené postupy.

Od listopadu 2025 se toto chování změnilo:

• Filtry oprávnění ACL nyní platí, i když používáte pouze klíče API služby nebo ověřování Entra ve všech verzích, které podporují ACL.
• Pokud je token uživatele vynechán, obsah chráněný seznamem ACL se nevrátí.
• Pokud chcete zobrazit všechny dokumenty pro řešení potíží, musíte explicitně zahrnout hlavičku se zvýšenými oprávněními ke čtení při použití verze 2026-05-01-preview rozhraní REST API nebo novější.

Tato aktualizace pomáhá chránit obsah, když aplikace nevynucuje osvědčené postupy pro ověřování tokenů.

Související obsah

• Kurz: Indexování metadat oprávnění z ADLS Gen2 a dotazování s výsledky filtrovanými oprávněními (Preview)
• Indexování seznamů řízení přístupu k dokumentům (ACL) pomocí nabízených rozhraní REST API (Preview)
• Použití indexeru ADLS Gen2 k ingestování metadat oprávnění a filtrování výsledků hledání na základě uživatelských přístupových práv (Preview)
• Použijte indexer objektů blob nebo zdroj znalostí pro příjem metadat oborů RBAC
• Použití indexeru SharePoint k příjmu metadat oprávnění a filtrování výsledků hledání na základě uživatelských přístupových práv (Preview)