Wymuszanie mechanizmów ACL i RBAC w czasie wykonywania zapytania w Wyszukiwanie AI platformy Azure (wersja zapoznawcza)

Kontrola dostępu w czasie zapytania (wersja zapoznawcza) zapewnia, że użytkownicy pobierają tylko wyniki wyszukiwania, do których mają uprawnienia dostępu, na podstawie ich tożsamości, członkostwa w grupach, ról lub atrybutów. Ta funkcja jest niezbędna do bezpiecznego wyszukiwania w przedsiębiorstwie i przepływów pracy opartych na zgodności.

Autoryzowany dostęp zależy od metadanych uprawnień pozyskanych podczas indeksowania. W przypadku źródeł danych indeksatora, które mają wbudowane modele dostępu, takie jak Azure Data Lake Storage (ADLS) Gen2 i SharePoint w Microsoft 365, indeksator może automatycznie ściągnąć metadane uprawnień dla każdego dokumentu. W przypadku innych źródeł danych musisz samodzielnie zebrać ładunek dokumentu, a ładunek musi zawierać zarówno zawartość, jak i skojarzone metadane uprawnień. Następnie użyjesz push API, aby załadować indeks.

W tym artykule wyjaśniono, jak skonfigurować zapytania korzystające z metadanych uprawnień do filtrowania wyników.

Wymagania wstępne

• Metadane uprawnień muszą znajdować się w polach ciągów znaków filterable. Nie będziesz używać filtru w zapytaniach, ale wyszukiwarka tworzy filtr wewnętrznie, aby wykluczyć nieautoryzowaną zawartość.

• Metadane uprawnień muszą składać się z uprawnień w stylu POSIX, które określają poziom dostępu oraz ID grupy lub użytkownika, albo - jeśli używasz zakresu RBAC - z identyfikatora zasobu kontenera w usłudze ADLS Gen2.

• W przypadku wymuszania opartego na mechanizmach ACL przy niestandardowym pozyskiwaniu danych przechowuj userIds i groupIds jako identyfikatory obiektów Microsoft Entra (GUID) w polach filtrowalnych. Podczas wykonywania kwerendy usługa dopasowuje tożsamości w x-ms-query-source-authorization do zapisanych identyfikatorów. Aby uzyskać szczegółowe informacje o schemacie, zobacz Indeksowanie list kontroli dostępu do dokumentów (ACL) przy użyciu wypychanych interfejsów API REST (wersja zapoznawcza).

• W zależności od źródła danych:

  • W przypadku źródeł danych usługi ADLS Gen2 należy skonfigurować listy kontroli dostępu (ACL) i/lub role kontroli dostępu opartej na rolach (RBAC) w Azure na poziomie kontenera.
  • W przypadku źródeł danych Blob w Azure musisz mieć przypisania ról w kontenerze. Do indeksowania metadanych uprawnień w indeksie można użyć wbudowanego indeksatora, źródła wiedzy lub API push.
  • W przypadku SharePoint źródeł danych należy skonfigurować listy kontroli dostępu (ACL). Możesz użyć wbudowanego indeksatora SharePoint i skonfigurować go z możliwościami pozyskiwania ACL. Możesz również użyć indeksowanego SharePoint źródła wiedzy i skonfigurować je do wymuszania uprawnień na poziomie dokumentu. Uprawnienia oparte na grupach, w tym Grupy platformy Microsoft 365, są obsługiwane pod warunkiem, że są importowane jako identyfikatory obiektów Entra. Rozszerzanie grupy odbywa się w czasie wykonywania zapytań przez Microsoft Graph.

• Użyj najnowszej wersji zapoznawczej REST API lub pakietu Azure SDK w najnowszej wersji zapoznawczej, aby wysłać zapytanie do indeksu lub źródła wiedzy. Ta wersja interfejsu API obsługuje zapytania wewnętrzne, które filtrują nieautoryzowane wyniki.

Ograniczenia

• Jeśli ocena ACL zakończy się niepowodzeniem (na przykład interfejs Graph API jest niedostępne), usługa zwraca 5xx i nie zwraca częściowo filtrowanego zestawu wyników.

• Aktualność listy ACL zależy od sposobu importowania danych. Aby uniknąć nieaktualnych decyzji dotyczących autoryzacji, zaplanuj, jak każde źródło propaguje zmiany uprawnień do indeksu:

  • Zaplanowany indeksator programu SharePoint odświeża zmiany uprawnień na poziomie elementów przy każdym uruchomieniu. Zmiany zakresu nadrzędnego (witryny, biblioteki, listy lub folderu), które są dziedziczone przez elementy podrzędne, wymagają ponownej synchronizacji.
  • Indeksator usługi ADLS Gen2 wymaga ponownej synchronizacji w celu odświeżenia list ACL.
  • Importowanie niestandardowe lub w trybie push wymaga ponownego zaimportowania dokumentów, których to dotyczy.

• Widoczność dokumentu wymaga obu następujących elementów:

  • Rola RBAC aplikacji wywołującej (nagłówek autoryzacji).
  • Tożsamość użytkownika przekazywana przez x-ms-query-source-authorization.

• Początkowe zapytania oparte na ACL mogą cechować się wyższymi opóźnieniami niż kolejne żądania ze względu na narzut związany z buforowaniem i ustalaniem uprawnień.

• W przypadku zindeksowanej zawartości programu SharePoint grupa Microsoft Entra zagnieżdżona w grupie programu SharePoint nie jest rozwijana. Microsoft Entra rozpoznawanie grup przechodnich nie obsługuje tej mieszanej relacji. Zobacz Obsługiwane relacje między grupami.

Limity wpisów ACL na źródło danych

Limity wpisu listy kontroli dostępu (ACL) określają, ile odrębnych rekordów uprawnień może być skojarzonych z plikiem, folderem lub elementem w połączonym źródle danych. Każdy wpis reprezentuje tożsamość pojedynczego użytkownika lub grupy i prawa dostępu przyznane tej tożsamości (na przykład Odczyt, Zapis lub Wykonywanie).

Maksymalna liczba wpisów listy ACL obsługiwanych przez funkcje Wyszukiwanie AI platformy Azure różni się w zależności od typu źródła danych:

Azure Data Lake Storage Gen2 (ADLS Gen2): Każdy plik lub katalog może mieć do 32 uprawnienia listy ACL. W tym kontekście wpis oznacza podmiot (użytkownika lub grupę) z określonym zestawem uprawnień. Przykład: przypisanie dostępu do odczytu "Wszyscy" oraz dostępu do wykonywania "użytkownikom Azure" będzie liczone jako dwa wpisy listy ACL.

SharePoint w Microsoft 365: SharePoint źródło danych w funkcji wyszukiwania obsługuje maksymalnie 1000 wpisów uprawnień na plik. Każdy wpis reprezentuje unikatowe przypisanie użytkownika lub grupy na liście uprawnień elementu. Różni się to od ogólnych limitów unikatowych zakresów uprawnień na listę lub bibliotekę, która określa, ile elementów może mieć unikatowe uprawnienia.

Limity określają, w jakim stopniu Wyszukiwanie AI platformy Azure może honorować uprawnienia na poziomie elementu podczas indeksowania lub filtrowania wyników wyszukiwania. Jeśli element przekracza te limity wpisów listy ACL, uprawnienia wykraczające poza ten limit mogą nie być egzekwowane podczas wykonywania zapytania.

Jak działa egzekwowanie w czasie wykonywania zapytania

W tej sekcji wymieniono kolejność operacji egzekwowania listy kontroli dostępu (ACL) podczas przetwarzania zapytania. Operacje różnią się w zależności od tego, czy używasz zakresu Azure RBAC, czy identyfikatorów grup lub użytkowników Microsoft Entra ID.

Wprowadzenie uprawnień użytkownika

Aplikacja użytkownika końcowego uwzględnia token dostępu zapytania jako część żądania wyszukiwania, a token ten zazwyczaj odzwierciedla tożsamość użytkownika. W poniższej tabeli wymieniono źródła uprawnień użytkownika, które są obsługiwane przez Wyszukiwanie AI platformy Azure do egzekwowania list ACL:

2. Konstrukcja filtru zabezpieczeń

Wewnętrznie Wyszukiwanie AI platformy Azure dynamicznie konstruuje filtry zabezpieczeń na podstawie podanych uprawnień użytkownika. Te filtry zabezpieczeń są automatycznie dołączane do wszystkich filtrów, które mogą pojawić się w zapytaniu, jeśli indeks ma włączoną opcję filtru uprawnień.

W przypadku kontroli dostępu opartej na rolach (Azure RBAC), uprawnienia są listami ciągów identyfikatorów zasobów. W źródle danych magazynu musi istnieć przypisanie roli Azure (Storage Blob Data Reader), które udziela dostępu do tokenu podmiotu zabezpieczeń w nagłówku autoryzacji. Filtr wyklucza dokumenty, jeśli nie ma przypisania roli dla podmiotu, który stoi za tokenem dostępu w żądaniu.

3. Filtrowanie wyników

Filtr zabezpieczeń skutecznie dopasowuje identyfikatory użytkowników, identyfikatory grup oraz zakres rbac z żądania do każdej listy ACL w indeksie wyszukiwania, aby ograniczyć zwracane wyniki do tych, do których użytkownik ma dostęp. Należy pamiętać, że każdy filtr jest stosowany niezależnie, a dokument jest uznawany za autoryzowany, jeśli jakikolwiek filtr zakończy się pomyślnie. Jeśli na przykład użytkownik ma dostęp do dokumentu za pośrednictwem identyfikatorów userId, ale nie za pomocą identyfikatorów groupId, dokument jest nadal uznawany za prawidłowy i zwracany do użytkownika.

Grupy SharePoint w czasie wykonywania zapytania

Począwszy od interfejsu API REST 2026-05-01-preview usługa Wyszukiwanie AI platformy Azure może podczas wykonywania zapytań uwzględniać członkostwo w grupach witryny programu SharePoint, takich jak Właściciele, Członkowie, Odwiedzający i niestandardowe grupy witryny. Aby włączyć ten scenariusz, indeks musi zawierać następujące elementy:

• Właściwość sharePointConnectorAppRegistration, która odwołuje się do poświadczenia tożsamości federacyjnej aplikacji Microsoft Entra używanej do wywoływania usługi SharePoint w imieniu użytkownika.
• Pole oznaczone atrybutem sharepointSiteUrl: true, które przechowuje adres URL witryny SharePoint dla każdego indeksowanego elementu (zazwyczaj o nazwie SharePointSiteUrl i wypełniane z pola źródłowego metadata_spo_site_url).

W czasie wykonywania kwerendy usługa Wyszukiwanie AI platformy Azure używa zarejestrowanej aplikacji oraz adresu URL witryny dla każdego dokumentu kandydującego, aby ustalić członkostwo użytkownika wywołującego w grupach SharePoint w tej witrynie. Wyznaczone grupy są dopasowywane do wartości poprzedzonych prefiksem spg:, przechowywanych w polu filtru uprawnień groupIds. Prefiks spg: odróżnia grupy witryn programu SharePoint od identyfikatorów obiektów grup Microsoft Entra, które są przechowywane bez prefiksu.

Aby uzyskać szczegółowe informacje o konfiguracji i ograniczenia, zobacz Konfigurowanie obsługi grup SharePoint.

Jeśli filtrowanie uprawnień SharePoint zwraca brakujące lub nieoczekiwane wyniki, zobacz Rozwiązywanie problemów z filtrowaniem uprawnień SharePoint.

Przykład: zapytanie z wymuszaniem grupy witryn programu SharePoint

Żądanie jest identyczne ze standardowym zapytaniem wymuszanym przez mechanizm ACL. Usługa wyszukiwania używa elementu sharePointConnectorAppRegistration indeksu do określania członkostwa w grupie programu SharePoint w imieniu obiektu wywołującego. Uwzględnij GroupIds w klauzuli select, aby zobaczyć wartości z prefiksem spg: w odpowiedzi.

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

Przykład zapytania

Oto przykład żądania zapytania z sample code. Token zapytania jest tokenem dostępu Microsoft Entra dla użytkownika wykonującego zapytanie.

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

Podwyższony poziom uprawnień do badania nieprawidłowych wyników (wersja zapoznawcza)

Debugowanie zapytań zawierających metadane uprawnień może być problematyczne, ponieważ wyniki wyszukiwania są specyficzne dla każdego użytkownika. Jako deweloper lub administrator może być konieczne podniesienie uprawnień, aby zwracać wyniki niezależnie od metadanych uprawnień, aby można było zbadać problemy z zapytaniami zwracającymi nieautoryzowaną zawartość.

Aby zbadać ten problem, musisz mieć następujące możliwości:

• Wyświetl zestaw dokumentów, które użytkownik końcowy może wyświetlić na podstawie uprawnień tego użytkownika.

• Wyświetl wszystkie dokumenty w indeksie, aby zbadać, dlaczego niektóre mogą nie być widoczne dla użytkownika końcowego.

Te zadania można wykonać, dodając nagłówek niestandardowy , x-ms-enable-elevated-read: truedo zapytania.

Uprawnienia do żądań odczytu z podwyższonym poziomem uprawnień

Musisz mieć uprawnienia Współautor danych indeksu wyszukiwania lub rolę niestandardową, która zawiera uprawnienie Elevate Read.

Zapytania są operacją warstwy danych, więc rola niestandardowa może składać się tylko z atomowych uprawnień warstwy danych. W przypadku roli niestandardowej dodaj uprawnienie Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read.

Dodaj nagłówek z podwyższonymi uprawnieniami odczytu do zapytania

Po skonfigurowaniu uprawnień możesz uruchomić zapytanie. Poniższy przykład to żądanie zapytania względem indeksu wyszukiwania.

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
}

Istotna zmiana zachowania funkcjonalności ACL w określonych zapoznawczych wersjach interfejsu API

Przed wersją interfejsu API REST 2025-11-01-preview wcześniejsze wersje zapoznawcze 2025-05-01-preview i 2025-08-01-preview zwracały wszystkie dokumenty podczas korzystania z klucza API usługi lub autoryzowanych ról Entra, nawet jeśli nie podano tokenu użytkownika. Aplikacje, które nie zweryfikowały obecności tokenu użytkownika, mogą przypadkowo uwidocznić wyniki dla użytkowników końcowych, jeśli nie zostały prawidłowo zaimplementowane lub zgodnie z najlepszymi rozwiązaniami.

Począwszy od listopada 2025 r., to zachowanie uległo zmianie:

• Filtry uprawnień ACL mają teraz zastosowanie nawet w przypadku używania tylko kluczy API usługi lub uwierzytelniania Entra we wszystkich wersjach, które obsługują ACL.
• Jeśli token użytkownika zostanie pominięty, nie jest zwracana zawartość chroniona przez listę ACL.
• Aby wyświetlić wszystkie dokumenty na potrzeby rozwiązywania problemów, należy jawnie dołączyć nagłówek elevated-read podczas korzystania z interfejsu API REST w wersji 2026-05-01-preview lub nowszej.

Ta aktualizacja pomaga chronić zawartość, gdy aplikacje nie wymuszają najlepszych rozwiązań dotyczących walidacji tokenu.

Treści powiązane

• Samouczek: indeksowanie metadanych uprawnień z ADLS Gen2 i wykonywanie zapytań z wynikami filtrowanymi według uprawnień (wersja zapoznawcza)
• Indeksowanie list kontroli dostępu do dokumentów (ACL) przy użyciu interfejsów API REST typu push (wersja zapoznawcza)
• Używanie indeksatora usługi ADLS Gen2 do pozyskiwania metadanych uprawnień i filtrowania wyników wyszukiwania na podstawie praw dostępu użytkowników (wersja zapoznawcza)
• Użyj indeksatora obiektów blob lub źródła wiedzy, aby pozyskać metadane zakresów RBAC
• Używanie indeksatora SharePoint do pozyskiwania metadanych uprawnień i filtrowania wyników wyszukiwania na podstawie praw dostępu użytkowników (wersja zapoznawcza)