Filtry zabezpieczeń służące do przycinania wyników wyszukiwania sztucznej inteligencji platformy Azure przy użyciu dzierżaw i tożsamości firmy Microsoft

  • Artykuł

W tym artykule pokazano, jak używać tożsamości zabezpieczeń firmy Microsoft Entra 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 opisano następujące zadania:

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

Wymagania 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 tym przypadku użycia założono, że korespondencja jeden do jednego między zabezpieczanym elementem (takim jak aplikacja kolegium osoby) i polem bezpieczeństwa określającym, kto ma dostęp do tego elementu (personel przyjęć).

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

Aplikacja musi być również zarejestrowana w usłudze Microsoft Entra ID jako aplikacja wielodostępna, zgodnie z opisem w poniższej procedurze.

Rejestrowanie aplikacji przy użyciu identyfikatora Entra firmy Microsoft

Ten krok integruje aplikację z identyfikatorem Entra firmy Microsoft w celu akceptowania logowania kont użytkowników i grup. Jeśli nie jesteś administratorem dzierżawy w organizacji, może być konieczne utworzenie nowej dzierżawy , aby wykonać następujące kroki.

  1. W witrynie Azure Portal znajdź dzierżawę identyfikatora entra firmy Microsoft.

  2. Po lewej stronie w obszarze Zarządzaj wybierz 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 podać ten ciąg aplikacji.

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

  6. Skopiuj identyfikator katalogu (dzierżawy).

    Screenshot of the application ID in the Essentials section.

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

  8. Wybierz pozycję Microsoft Graph , a następnie wybierz pozycję Delegowane uprawnienia.

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

    • Directory.ReadWrite.All
    • Group.ReadWrite.All
    • User.ReadWrite.All

    Program Microsoft Graph udostępnia interfejs API, który umożliwia programowy dostęp do identyfikatora Entra firmy Microsoft 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 pozycję Udziel zgody administratora dla dzierżawy , aby ukończyć proces wyrażania zgody.

Tworzenie użytkowników i grup

Jeśli dodasz wyszukiwanie do ustalonej aplikacji, możesz mieć istniejące identyfikatory użytkowników i grup w identyfikatorze Entra firmy Microsoft. 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 przyjęć uczelni byłoby to identyfikatory bezpieczeństwa dla pracowników przyjęć.

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 wystarczająco często, aby pobierać zmiany w członkostwie w 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. Tworzenie grupy

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. Tworzenie 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ć opóźnienie sieci, można buforować skojarzenia grupy użytkowników, aby po wysłaniu żądania wyszukiwania grupy użytkowników grupy grupy zostały zwrócone z pamięci podręcznej grupy, zapisując roundtrip do identyfikatora Firmy Microsoft Entra. Interfejs API usługi Microsoft Entra Batch umożliwia wysłanie pojedynczego żądania HTTP z wieloma użytkownikami i skompilowanie pamięci podręcznej.

Usługa Microsoft Graph została zaprojektowana z myślą o obsłudze 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.

Indeksowanie dokumentu z dozwolonymi grupami

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 treść żądania PUT w indeksie usługi Azure AI Search będzie zawierać esej lub transkrypcję wnioskodawcy wraz z identyfikatorem grupy z uprawnieniami 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 statycznym 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 wygasła, wydaj żą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.

Następne kroki

W tym przewodniku przedstawiono wzorzec używania logowania firmy Microsoft Entra do filtrowania dokumentów w wynikach usługi Azure AI Search, przycinając wyniki dokumentów, które nie są zgodne z filtrem podanym w żądaniu. Aby uzyskać alternatywny wzorzec, który może być prostszy lub aby ponownie zapoznać się z innymi funkcjami zabezpieczeń, zobacz poniższe linki.