Udostępnij za pośrednictwem

Filtry zabezpieczeń do przycinania wyników wyszukiwania usługi Azure AI przy użyciu usługi Azure Active Directory

  • Artykuł

W tym artykule pokazano, jak używać tożsamości zabezpieczeń wraz z filtrami w usłudze Azure AI Search w celu przycinania wyników wyszukiwania na podstawie członkostwa w grupie użytkowników.

W tym artykule omówiono następujące zadania:

  • Tworzenie grup i użytkowników
  • Kojarzenie użytkownika z utworzoną grupą
  • Buforowanie nowych grup
  • Indeksowanie dokumentów ze skojarzonymi grupami
  • Wystawianie żądania wyszukiwania z filtrem identyfikatorów grup

Warunki wstępne

Indeks w usłudze Azure AI Search musi zawierać pole zabezpieczeń do przechowywania listy tożsamości grup mających dostęp do odczytu do dokumentu. W opisie tego przypadku użycia założono istnienie korespondencji jeden do jednego między elementem możliwym do zabezpieczenia (takim jak aplikacja na studia danej osoby) a polem zabezpieczeń określającym, kto ma dostęp do tego elementu (pracownicy działu rekrutacji).

Aby tworzyć użytkowników, grupy i skojarzenia, musisz mieć uprawnienia administratora dzierżawy (właściciela lub administratora).

Twoja aplikacja musi być również zarejestrowana jako aplikacja wielodostępna, zgodnie z opisem w poniższej procedurze.

Rejestrowanie aplikacji w usłudze Azure Active Directory

Ten krok integruje aplikację z usługą Azure Active Directory w celu akceptowania logowania kont użytkowników i grup. Jeśli nie jesteś administratorem tenanta w swojej organizacji, może być konieczne utworzenie nowego tenanta, aby wykonać poniższe kroki.

  1. W Azure Portalznajdź dzierżawcę usługi Azure Active Directory.

  2. Po lewej stronie w obszarze Zarządzajwybierz pozycję Rejestracje aplikacji, a następnie wybierz pozycję Nowa rejestracja.

  3. Nadaj rejestracji nazwę, być może nazwę podobną do nazwy aplikacji wyszukiwania. Zapoznaj się z tym artykułem, aby uzyskać informacje o innych właściwościach opcjonalnych.

  4. Wybierz pozycję Zarejestruj.

  5. Po utworzeniu rejestracji aplikacji skopiuj identyfikator aplikacji (klienta). Musisz przekazać ten ciąg swojej aplikacji.

    Jeśli przechodzisz przez DotNetHowToSecurityTrimming, wklej tę wartość do pliku app.config.

  6. Skopiuj identyfikator katalogu (dzierżawy).

  7. Po lewej stronie wybierz uprawnienia interfejsu API, a następnie wybierz Dodaj uprawnienie.

  8. Wybierz pozycję Microsoft Graph, a następnie wybierz pozycję Uprawnienia delegowane .

  9. Wyszukaj i dodaj następujące delegowane uprawnienia:

    • Katalog.CzytajZapisz.Wszystko
    • Group.ReadWrite.All
    • User.ReadWrite.All

    Program Microsoft Graph udostępnia interfejs API, który umożliwia programowy dostęp do usługi Azure Active Directory za pośrednictwem interfejsu API REST. Przykładowy kod w tym przewodniku używa uprawnień do wywoływania interfejsu API programu Microsoft Graph do tworzenia grup, użytkowników i skojarzeń. Interfejsy API są również używane do buforowania identyfikatorów grup w celu szybszego filtrowania.

  10. Wybierz , aby udzielić zgody administratora dla dzierżawy i ukończyć proces wyrażania zgody.

Tworzenie użytkowników i grup

Jeśli dodasz wyszukiwanie do ustanowionej aplikacji, możesz mieć istniejące identyfikatory użytkowników i grup w usłudze Azure Active Directory. W takim przypadku możesz pominąć kolejne trzy kroki.

Jeśli jednak nie masz istniejących użytkowników, możesz użyć interfejsów API programu Microsoft Graph do utworzenia podmiotów zabezpieczeń. Poniższe fragmenty kodu pokazują, jak wygenerować identyfikatory, które stają się wartościami danych dla pola zabezpieczeń w indeksie usługi Azure AI Search. W naszej hipotetycznej aplikacji rekrutacyjnej na uczelnię byłyby to znaczniki bezpieczeństwa dla personelu rekrutacyjnego.

Członkostwo użytkowników i grup może być bardzo płynne, zwłaszcza w dużych organizacjach. Kod, który tworzy tożsamości użytkowników i grup, powinien być uruchamiany na tyle często, aby uwzględniać zmiany w członkostwie organizacji. Podobnie indeks usługi Azure AI Search wymaga podobnego harmonogramu aktualizacji, aby odzwierciedlał bieżący stan dozwolonych użytkowników i zasobów.

Krok 1: Utwórz grupę

private static Dictionary<Group, List<User>> CreateGroupsWithUsers(string tenant)
{
    Group group = new Group()
    {
        DisplayName = "My First Prog Group",
        SecurityEnabled = true,
        MailEnabled = false,
        MailNickname = "group1"
    };

Krok 2: Utwórz użytkownika 

User user1 = new User()
{
    GivenName = "First User",
    Surname = "User1",
    MailNickname = "User1",
    DisplayName = "First User",
    UserPrincipalName = String.Format("user1@{0}", tenant),
    PasswordProfile = new PasswordProfile() { Password = "********" },
    AccountEnabled = true
};

Krok 3. Kojarzenie użytkownika i grupy

List<User> users = new List<User>() { user1, user2 };
Dictionary<Group, List<User>> groups = new Dictionary<Group, List<User>>() { { group, users } };

Krok 4. Buforowanie identyfikatorów grup

Opcjonalnie, aby zmniejszyć latencję sieci, można buforować skojarzenia użytkowników z grupami, aby po wysłaniu żądania wyszukiwania grupy były zwracane z pamięci podręcznej, zapisując powrotną podróż. Za pomocą interfejsu API usługi Batch można wysłać pojedyncze żądanie HTTP z wieloma użytkownikami i skompilować pamięć podręczną.

Program Microsoft Graph jest przeznaczony do obsługi dużej liczby żądań. Jeśli wystąpi przytłaczająca liczba żądań, program Microsoft Graph zakończy się niepowodzeniem żądania z kodem stanu HTTP 429. Aby uzyskać więcej informacji, zobacz ograniczanie przepustowości programu Microsoft Graph.

Indeksuj dokument w ich dozwolonych grupach

Operacje zapytań w usłudze Azure AI Search są wykonywane za pośrednictwem indeksu usługi Azure AI Search. W tym kroku operacja indeksowania importuje przeszukiwalne dane do indeksu, w tym identyfikatory używane jako filtry zabezpieczeń.

Usługa Azure AI Search nie uwierzytelnia tożsamości użytkowników ani nie udostępnia logiki określania zawartości, którą użytkownik ma uprawnienia do wyświetlania. W przypadku przycinania zabezpieczeń przyjęto założenie, że należy podać skojarzenie między poufnym dokumentem a identyfikatorem grupy mającym dostęp do tego dokumentu, zaimportowanym bez zmian do indeksu wyszukiwania.

W hipotetycznym przykładzie zawartość żądania PUT w indeksie usługi Azure AI Search będzie zawierać esej lub transkrypcję kandydata wraz z identyfikatorem grupy posiadającej uprawnienia do wyświetlania tej zawartości.

W przykładzie ogólnym używanym w przykładzie kodu dla tego przewodnika akcja indeksu może wyglądać następująco:

private static void IndexDocuments(string indexName, List<string> groups)
{
    IndexDocumentsBatch<SecuredFiles> batch = IndexDocumentsBatch.Create(
        IndexDocumentsAction.Upload(
            new SecuredFiles()
            {
                FileId = "1",
                Name = "secured_file_a",
                GroupIds = new[] { groups[0] }
            }),
              ...
            };

IndexDocumentsResult result = searchClient.IndexDocuments(batch);

Wystawianie żądania wyszukiwania

W celach przycinania zabezpieczeń wartości w polu zabezpieczeń w indeksie są wartościami statycznymi używanymi do dołączania lub wykluczania dokumentów w wynikach wyszukiwania. Jeśli na przykład identyfikator grupy dla przyjęć to "A11B22C33D44-E55F66G77-H88I99JKK", wszystkie dokumenty w indeksie usługi Azure AI Search o tym identyfikatorze w polu zabezpieczeń są uwzględniane (lub wykluczone) w wynikach wyszukiwania wysyłanych z powrotem do obiektu wywołującego.

Aby filtrować dokumenty zwracane w wynikach wyszukiwania na podstawie grup użytkowników wysyłających żądanie, zapoznaj się z poniższymi krokami.

Krok 1. Pobieranie identyfikatorów grupy użytkownika

Jeśli grupy użytkownika nie zostały jeszcze zbuforowane lub pamięć podręczna (cache) wygasła, wykonaj żądanie grup.

private static async void RefreshCache(IEnumerable<User> users)
{
    HttpClient client = new HttpClient();
    var userGroups = await _microsoftGraphHelper.GetGroupsForUsers(client, users);
    _groupsCache = new ConcurrentDictionary<string, List<string>>(userGroups);
}

Krok 2. Tworzenie żądania wyszukiwania

Zakładając, że masz członkostwo w grupach użytkownika, możesz wysłać żądanie wyszukiwania z odpowiednimi wartościami filtru.

private static void SearchQueryWithFilter(string user)
{
    // Using the filter below, the search result will contain all documents that their GroupIds field   
    // contain any one of the Ids in the groups list
    string filter = String.Format("groupIds/any(p:search.in(p, '{0}'))", string.Join(",", String.Join(",", _groupsCache[user])));
    SearchOptions searchOptions =
        new SearchOptions()
        {
            Filter = filter
        };
    searchOptions.Select.Add("name");

    SearchResults<SecuredFiles> results = searchClient.Search<SecuredFiles>("*", searchOptions);

    Console.WriteLine("Results for groups '{0}' : {1}", _groupsCache[user], results.GetResults().Select(r => r.Document.Name));
}

Krok 3. Obsługa wyników

Odpowiedź zawiera filtrowaną listę dokumentów składających się z tych, które użytkownik ma uprawnienia do wyświetlania. W zależności od sposobu konstruowania strony wyników wyszukiwania może być konieczne uwzględnienie wskazówek wizualnych, aby odzwierciedlić filtrowany zestaw wyników.

Wnioski

W tym przewodniku zapoznałeś się z wzorcem używania logowań użytkowników do filtrowania dokumentów w wynikach usługi Azure AI Search, ograniczając wyniki do dokumentów zgodnych z filtrem podanym w żądaniu.