Kontrola dostępu na poziomie dokumentu w usłudze Azure AI Search

Usługa Azure AI Search obsługuje kontrolę dostępu na poziomie dokumentu, umożliwiając organizacjom wymuszanie precyzyjnych uprawnień na poziomie dokumentu od pozyskiwania danych przez wykonywanie zapytań. Ta funkcja jest niezbędna do tworzenia bezpiecznych systemów agentowych sztucznej inteligencji, przypinania danych, aplikacji generacji Retrieval-Augmented (RAG) i rozwiązań związanych z wyszukiwaniem w przedsiębiorstwie, które wymagają kontroli autoryzacyjnych na poziomie dokumentu.

Metody kontroli dostępu na poziomie dokumentu

Wzorzec przycinania zabezpieczeń przy użyciu filtrów

W przypadku scenariuszy, w których integracja natywnych zakresów ACL/RBAC nie jest opłacalna, zalecamy filtrowanie ciągów zabezpieczeń w celu przycinania wyników na podstawie kryteriów wykluczania. Wzorzec zawiera następujące składniki:

• Aby przechowywać tożsamości użytkowników lub grup, utwórz pole ciągu w indeksie.
• Załaduj indeks za pomocą dokumentów źródłowych, które zawierają powiązane listy ACL.
• Uwzględnij wyrażenie filtru w logice zapytania w celu dopasowania do ciągu.
• W czasie wykonania zapytania uzyskaj tożsamość dzwoniącego.
• Przekaż tożsamość obiektu wywołującego jako ciąg filtru.
• Wyniki są filtrowane, aby wykluczyć wszystkie dopasowania, które nie zawierają ciągu znaków tożsamości użytkownika lub grupy.

Możesz użyć interfejsów API modelu push lub pull. Ponieważ takie podejście jest niezależne od interfejsu API, wystarczy upewnić się, że indeks i zapytanie mają prawidłowe ciągi (tożsamości) dla kroku filtrowania.

Takie podejście jest przydatne w przypadku systemów z niestandardowymi modelami dostępu lub platformami zabezpieczeń innych niż Microsoft. Aby uzyskać więcej informacji na ten temat, zobacz Filtry zabezpieczeń dotyczące usuwania wyników w usłudze Azure AI Search.

Wzorzec natywnej obsługi listy kontroli dostępu (ACL) podobnej do POSIX i zakresów uprawnień opartych na rolach (wersja próbna)

Natywna obsługa jest oparta na użytkownikach i grupach firmy Microsoft powiązanych z dokumentami, które chcesz indeksować i wykonywać zapytania.

Kontenery usługi Azure Data Lake Storage (ADLS) Gen2 obsługują listy ACL w kontenerze i plikach. W przypadku usługi ADLS Gen2 zachowywanie zakresu RBAC na poziomie dokumentu jest natywnie obsługiwane, gdy używasz indeksatora usługi ADLS Gen2 lub źródła wiedzy obiektu blob (obsługuje usługę ADLS Gen2) oraz interfejsu API w wersji zapoznawczej do przyjmowania zawartości. W przypadku blobów na platformie Azure, które korzystają z indeksatora blobów lub źródła wiedzy platformy Azure, zachowanie zakresu RBAC odbywa się na poziomie kontenera.

Dla zawartości zabezpieczonej za pomocą listy ACL zalecamy dostęp grupowy zamiast dostępu indywidualnego użytkownika, aby ułatwić zarządzanie. Wzorzec zawiera następujące składniki:

• Zacznij od dokumentów lub plików, które mają przydziały ACL.
• Włącz filtry uprawnień w indeksie.
• Dodaj filtr uprawnień do pola ciągu w indeksie.
• Załaduj indeks dokumentami źródłowymi, które mają skojarzone listy kontroli dostępu.
• Wykonaj zapytanie względem indeksu, dodając x-ms-query-source-authorization w nagłówku żądania.

Aplikacja kliencka otrzymuje uprawnienia do odczytu do indeksu za pomocą roli Czytelnik danych indeksu wyszukiwania lub Współautor danych indeksu wyszukiwania . Dostęp w czasie zapytania jest określany przez metadane uprawnień użytkownika lub grupy w indeksowanej zawartości. Zapytania zawierające filtr uprawnień przekazują token użytkownika lub grupy, tak jak x-ms-query-source-authorization w nagłówku żądania. Gdy używasz filtrów uprawnień w czasie wykonywania zapytań, usługa Azure AI Search sprawdza dwie rzeczy:

• Najpierw sprawdza uprawnienia Czytelnik danych indeksu wyszukiwania , które umożliwia aplikacji klienckiej dostęp do indeksu.

• Po drugie, biorąc pod uwagę dodatkowy token w żądaniu, sprawdza uprawnienia użytkownika lub grupy w dokumentach zwracanych w wynikach wyszukiwania, z wyłączeniem tych, które nie są zgodne.

Aby wprowadzić metadane uprawnień do indeksu, możesz użyć interfejsu API modelu push, przesyłając dowolne dokumenty JSON do indeksu wyszukiwania, gdzie ładunek zawiera pole tekstowe zapewniające listy ACL podobne do modelu POSIX dla każdego dokumentu. Ważną różnicą między tym podejściem a przycinaniem zabezpieczeń jest to, że metadane filtru uprawnień w indeksie i zapytaniu są rozpoznawane jako uwierzytelnianie Microsoft Entra ID, natomiast obejście przycinania zabezpieczeń polega na prostym porównaniu tekstu. Ponadto możesz użyć zestawu Graph SDK do pobrania tożsamości.

Możesz również użyć interfejsów API modelu ściągania (indeksatora), jeśli źródłem danych jest usługa Azure Data Lake Storage (ADLS) Gen2, a Twój kod wywołuje interfejs API w wersji zapoznawczej do indeksowania.

Pobieranie metadanych uprawnień ACL podczas procesu przetwarzania danych (wersja zapoznawcza)

Sposób pobierania uprawnień ACL różni się w zależności od tego, czy przesyłasz zawartość dokumentów, czy też używasz indeksatora usługi ADLS Gen2.

Zacznij od interfejsu API w wersji zapoznawczej, który udostępnia funkcję:

• 2025-11-01-preview INTERFEJS API REST
• Pakiet wstępny zestawu Azure SDK dla języka Python
• Pakiet przedpremierowy Azure SDK dla .NET
• Pakiet wstępny zestawu Azure SDK dla języka Java

W przypadku podejścia modelu wypychania:

1. Upewnij się, że schemat indeksu został również utworzony przy użyciu zestawu SDK wersji zapoznawczej lub wersji wstępnej oraz że schemat ma filtry uprawnień.
2. Rozważ użycie zestawu SDK programu Microsoft Graph w celu uzyskania tożsamości grup lub użytkowników.
3. Użyj interfejsu API Index Documents lub równoważnego interfejsu API Azure SDK, aby przekazywać dokumenty wraz ze skojarzonymi metadanymi uprawnień do indeksu wyszukiwania.

W przypadku modelu wejściowego indeksatora dla ADLS Gen2 lub źródła wiedzy Blob (ADLS Gen2):

1. Sprawdź, czy pliki w katalogu są zabezpieczone przy użyciu modelu kontroli dostępu usługi ADLS Gen2.
2. Użyj interfejsu API REST tworzenia indeksatora lub interfejsu API REST tworzenia źródła wiedzy albo równoważnego interfejsu API zestawu Azure SDK, aby utworzyć indeksator, indeks i źródło danych.

Wzorzec dla programu SharePoint na platformie Microsoft 365 — podstawowe wprowadzanie uprawnień ACL (wersja zapoznawcza)

W przypadku programu SharePoint w zawartości platformy Microsoft 365 usługa Azure AI Search może stosować uprawnienia na poziomie dokumentu na podstawie list ACL programu SharePoint. Ta integracja promuje, że tylko użytkownicy lub grupy z dostępem do dokumentu źródłowego w programie SharePoint mogą pobrać go w wynikach wyszukiwania, gdy tylko uprawnienia zostaną zsynchronizowane w indeksie. Uprawnienia są stosowane do indeksu na etapie początkowego pozyskiwania dokumentów.

Obsługa ACL dla SharePoint jest dostępna w wersji zapoznawczej za pośrednictwem indeksatora SharePoint przy użyciu interfejsu API REST 2025-11-01-preview lub obsługiwanego zestawu SDK. Indeksator wyodrębnia metadane uprawnień do pliku i elementu listy oraz zachowuje je w indeksie wyszukiwania, gdzie jest używany do wymuszania kontroli dostępu w czasie wykonywania zapytań.

Wzorzec zawiera następujące składniki:

• Użyj indeksatora SharePoint na platformie Microsoft 365 z uprawnieniami aplikacji do odczytywania zawartości witryny SharePoint oraz pełnymi uprawnieniami do odczytu listy ACL. Postępuj zgodnie z instrukcjami konfiguracji ACL indeksatora programu SharePoint dotyczącymi włączania i ograniczeń.
• Podczas początkowego indeksowania, wpisy listy kontroli dostępu (ACL) programu SharePoint (użytkowników i grup) są przechowywane jako metadane uprawnień w indeksie wyszukiwania.
• Aby uzyskać przyrostowe indeksowanie list ACL, zapoznaj się z dostępnymi mechanizmami ponownej synchronizacji listy ACL programu SharePoint dostępnymi w publicznej wersji zapoznawczej.
• W czasie wykonywania zapytania usługa Azure AI Search sprawdza podmiot Microsoft Entra w tokenie zapytania względem metadanych ACL programu SharePoint przechowywanych w indeksie. Wyklucza on wszystkie dokumenty, do których obiekt wywołujący nie ma uprawnień dostępu.

W trybie podglądu w listach ACL programu SharePoint obsługiwane są tylko następujące typy podmiotów:

• Konta użytkowników usługi Microsoft Entra
• Microsoft Entra grup zabezpieczeń
• Grupy platformy Microsoft 365
• Grupy zabezpieczeń z obsługą poczty

Grupy programu SharePoint nie są obsługiwane w wersji zapoznawczej.

Aby uzyskać szczegółowe informacje o konfiguracji i pełne ograniczenia, zobacz How to index SharePoint in Microsoft 365 document-level permissions (preview) (Jak indeksować program SharePoint w uprawnieniach na poziomie dokumentu platformy Microsoft 365 (wersja zapoznawcza).

Wzorzec etykiet poufności usługi Microsoft Purview (wersja zapoznawcza)

Usługa Azure AI Search może pozyskiwać i wymuszać etykiety poufności usługi Microsoft Purview na potrzeby kontroli dostępu na poziomie dokumentu, rozszerzając zasady ochrony informacji z usługi Microsoft Purview do aplikacji wyszukiwania i pobierania.

Po włączeniu pozyskiwania etykiet, usługa Azure AI Search wyodrębnia metadane dotyczące poufności z obsługiwanych źródeł danych. Należą do nich: Azure Blob Storage, Azure Data Lake Storage Gen2 (ADLS Gen2), SharePoint na platformie Microsoft 365 i Microsoft OneLake. Wyodrębnione etykiety są przechowywane w indeksie wraz z zawartością dokumentu.

Podczas przetwarzania zapytania usługa Azure AI Search sprawdza etykietę poufności każdego dokumentu, token użytkownika Microsoft Entra oraz zasady Purview organizacji, aby określić dostęp. Dokumenty są zwracane tylko wtedy, gdy tożsamość użytkownika i uprawnienia oparte na etykietach zezwalają na dostęp w ramach skonfigurowanych zasad usługi Purview.

Wzorzec zawiera następujące składniki:

• Skonfiguruj indeks, źródło danych i indeksator (do celów planowania) przy użyciu interfejsu API REST 2025-11-01-preview lub odpowiedniego zestawu SDK obsługującego pozyskiwanie etykiet usługi Purview.
• Włącz tożsamość zarządzaną przypisaną przez system do usługi wyszukiwania. Następnie poproś administratora globalnego dzierżawy lub administratora ról uprzywilejowanych o udzielenie wymaganego dostępu, aby usługa wyszukiwania mogła bezpiecznie uzyskiwać dostęp do Microsoft Purview i wyodrębnić metadane etykiet.
• Zastosuj etykiety poufności do dokumentów przed indeksowaniem, aby można było je rozpoznać i zachować w trakcie importowania.
• W czasie wykonywania zapytania dołącz prawidłowy token firmy Microsoft Entra za pośrednictwem nagłówka x-ms-query-source-authorization do każdego żądania zapytania. Usługa Azure AI Search ocenia token i skojarzone metadane etykiet, aby wymusić kontrolę dostępu opartą na etykietach.

Wymuszanie etykiet poufności usługi Purview jest ograniczone do scenariuszy z jedną dzierżawą, wymaga uwierzytelniania RBAC, a w publicznej wersji zapoznawczej jest obsługiwane tylko za pośrednictwem interfejsu API REST lub zestawu SDK. Interfejsy API autouzupełniania i sugerowania nie są obecnie dostępne dla indeksów z obsługą Purview.

Aby uzyskać więcej informacji, zobacz Użyj indekserów Azure AI Search do pozyskiwania etykiet poufności Microsoft Purview.

Wymuszanie uprawnień na poziomie dokumentu w czasie wykonywania zapytania

W przypadku natywnych zapytań opartych na tokenach usługa Azure AI Search weryfikuje token Microsoft Entra użytkownika, przycinając zestawy wyników w celu uwzględnienia tylko dokumentów, do których użytkownik ma uprawnienia dostępu.

Automatyczne przycinanie można osiągnąć, dołączając token Microsoft Entra użytkownika do żądania zapytania. Aby uzyskać więcej informacji, zobacz Zastosowanie ACL w czasie zapytania i egzekwowanie RBAC w usłudze Azure AI Search.

Zalety kontroli dostępu na poziomie dokumentu

Kontrola dostępu na poziomie dokumentu ma kluczowe znaczenie dla ochrony poufnych informacji w aplikacjach opartych na sztucznej inteligencji. Pomaga to organizacjom tworzyć systemy zgodne z zasadami dostępu, zmniejszając ryzyko ujawnienia nieautoryzowanych lub poufnych danych. Dzięki integracji reguł dostępu bezpośrednio z potokiem wyszukiwania systemy sztucznej inteligencji mogą zapewniać odpowiedzi uziemione w bezpiecznych i autoryzowanych informacjach.

Przenosząc odpowiedzialność za egzekwowanie uprawnień do rozwiązania Azure AI Search, deweloperzy mogą skupić się na budowaniu wysokiej jakości systemów do pobierania i oceny. Takie podejście pomaga zmniejszyć potrzebę obsługi grup zagnieżdżonych, pisania filtrów niestandardowych lub ręcznego przycinania wyników wyszukiwania.

Uprawnienia na poziomie dokumentu w usłudze Azure AI Search zapewniają strukturę wymuszającą mechanizmy kontroli dostępu zgodne z zasadami organizacyjnymi. Korzystając z list kontroli dostępu (ACL) opartych na Microsoft Entra i ról opartych na Microsoft RBAC, organizacje mogą tworzyć systemy, które zapewniają solidną zgodność i promują zaufanie wśród użytkowników. Te wbudowane funkcje zmniejszają potrzebę kodowania niestandardowego, oferując ustandaryzowane podejście do zabezpieczeń na poziomie dokumentu.

Samouczki i przykłady

Przyjrzyj się bliżej kontroli dostępu na poziomie dokumentu w usłudze Azure AI Search, aby zapoznać się z większą liczbą artykułów i przykładów.

• Samouczek: indeksowanie metadanych uprawnień usługi ADLS Gen2 przy użyciu indeksatora
• azure-search-rest-samples/acl
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API
• azure-search-python-samples/Quickstart-Document-Permissions-Pull-API
• Aplikacja demonstracyjna: pozyskiwanie i honorowanie etykiet poufności

Treści powiązane

• Jak indeksować uprawnienia na poziomie dokumentu przy użyciu interfejsu API typu push
• Jak indeksować uprawnienia na poziomie dokumentu przy użyciu indeksatora usługi ADLS Gen2
• Jak indeksować uprawnienia na poziomie dokumentu przy użyciu programu SharePoint w indeksatorze platformy Microsoft 365
• Jak indeksować etykiety poufności przy użyciu indeksatorów
• Jak wykonywać zapytania przy użyciu uprawnień opartych na tokenach firmy Microsoft