Udostępnij za pośrednictwem

Nawiązywanie połączenia z usługą Azure AI Search przy użyciu ról

  • Artykuł

Platforma Azure udostępnia globalny system uwierzytelniania i autoryzacji opartej na rolach dla wszystkich usług działających na platformie. W usłudze Azure AI Search można przypisać role platformy Azure dla:

Dostęp poszczególnych użytkowników za pośrednictwem wyników wyszukiwania (czasami nazywanych zabezpieczeniami na poziomie wiersza lub zabezpieczeniami na poziomie dokumentu) nie jest obsługiwany za pośrednictwem przypisań ról. Aby obejść ten problem, utwórz filtry zabezpieczeń, które przycinają wyniki według tożsamości użytkownika, usuwając dokumenty, dla których żądający nie powinien mieć dostępu. Zobacz ten przykład czatu dla przedsiębiorstw przy użyciu programu RAG , aby zapoznać się z pokazem.

Przypisania ról są skumulowane i wszechobecne we wszystkich narzędziach i bibliotekach klienckich. Role można przypisywać przy użyciu dowolnej z obsługiwanych metod opisanych w dokumentacji kontroli dostępu opartej na rolach platformy Azure.

Dostęp oparty na rolach jest opcjonalny, ale zalecany. Alternatywą jest uwierzytelnianie oparte na kluczach, czyli domyślne.

Wymagania wstępne

Następujące role są wbudowane. Jeśli te role są niewystarczające, utwórz rolę niestandardową.

Rola Płaszczyzna opis
Właściciel Kontrolka i dane Pełny dostęp do płaszczyzny sterowania zasobu wyszukiwania, w tym możliwość przypisywania ról platformy Azure. Tylko rola Właściciel może włączać lub wyłączać opcje uwierzytelniania lub zarządzać rolami dla innych użytkowników. Administratorzy subskrypcji są domyślnie członkami.

Na płaszczyźnie danych ta rola ma taki sam dostęp jak rola Współautor usługi wyszukiwania. Obejmuje ona dostęp do wszystkich akcji płaszczyzny danych z wyjątkiem możliwości wykonywania zapytań lub indeksowania dokumentów.
Współautor Kontrolka i dane Ten sam poziom dostępu płaszczyzny kontroli co Właściciel, minus możliwość przypisywania ról lub zmiany opcji uwierzytelniania.

Na płaszczyźnie danych ta rola ma taki sam dostęp jak rola Współautor usługi wyszukiwania. Obejmuje ona dostęp do wszystkich akcji płaszczyzny danych z wyjątkiem możliwości wykonywania zapytań lub indeksowania dokumentów.
Czytelnik Kontrolka i dane Dostęp do odczytu w całej usłudze, w tym metryki wyszukiwania, metryki zawartości (wykorzystany magazyn, liczba obiektów) oraz definicje obiektów zasobów płaszczyzny danych (indeksy, indeksatory itd.). Nie może jednak odczytywać kluczy interfejsu API ani odczytywać zawartości w indeksach.
Współautor usługi wyszukiwania Kontrolka i dane Dostęp do odczytu i zapisu do definicji obiektów (indeksy, aliasy, mapy synonimów, indeksatory, źródła danych i zestawy umiejętności). Ta rola dotyczy deweloperów, którzy tworzą obiekty, oraz administratorów, którzy zarządzają usługą wyszukiwania i jej obiektami, ale bez dostępu do zawartości indeksu. Ta rola służy do tworzenia, usuwania i wyświetlania indeksów, pobierania definicji indeksów, pobierania informacji o usłudze (statystyk i przydziałów), analizatorów testów, tworzenia map synonimów, indeksatorów, źródeł danych i zestawów umiejętności oraz zarządzania nimi. Zobacz Microsoft.Search/searchServices/* listę uprawnień.
Współautor danych indeksu wyszukiwania Data Dostęp do odczytu i zapisu do zawartości w indeksach. Ta rola jest dla deweloperów lub właścicieli indeksów, którzy muszą importować, odświeżać lub wykonywać zapytania dotyczące kolekcji dokumentów indeksu. Ta rola nie obsługuje tworzenia indeksów ani zarządzania nimi. Domyślnie ta rola dotyczy wszystkich indeksów w usłudze wyszukiwania. Zobacz Udzielanie dostępu do pojedynczego indeksu , aby zawęzić zakres.
Czytnik danych indeksu wyszukiwania Data Dostęp tylko do odczytu na potrzeby wykonywania zapytań dotyczących indeksów wyszukiwania. Ta rola dotyczy aplikacji i użytkowników, którzy uruchamiają zapytania. Ta rola nie obsługuje dostępu do odczytu do definicji obiektów. Na przykład nie można odczytać definicji indeksu wyszukiwania ani pobrać statystyk usługi wyszukiwania. Domyślnie ta rola dotyczy wszystkich indeksów w usłudze wyszukiwania. Zobacz Udzielanie dostępu do pojedynczego indeksu , aby zawęzić zakres.

Połącz te role, aby uzyskać wystarczające uprawnienia dla twojego przypadku użycia.

Uwaga

Jeśli wyłączysz dostęp oparty na rolach platformy Azure, wbudowane role dla płaszczyzny sterowania (właściciel, współautor, czytelnik) będą nadal dostępne. Wyłączenie dostępu opartego na rolach spowoduje usunięcie tylko uprawnień związanych z danymi skojarzonych z tymi rolami. Jeśli role płaszczyzny danych są wyłączone, współautor usługi wyszukiwania jest odpowiednikiem współautora płaszczyzny sterowania.

Przypisywanie ról

W tej sekcji przypisz role dla:

Przypisywanie ról do administrowania usługą

Jako administrator usługi możesz utworzyć i skonfigurować usługę wyszukiwania oraz wykonać wszystkie operacje płaszczyzny sterowania opisane w interfejsie API REST zarządzania lub równoważnych bibliotekach klienckich. W zależności od roli można również wykonywać większość zadań interfejsu API REST wyszukiwania płaszczyzny danych.

  1. Zaloguj się w witrynie Azure Portal.

  2. Przejdź do usługi wyszukiwania.

  3. Wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami) w okienku nawigacji po lewej stronie.

  4. Wybierz pozycję + Dodaj>Dodaj przypisanie roli.

  5. Wybierz odpowiednią rolę:

    • Właściciel (pełny dostęp do wszystkich operacji płaszczyzny danych i płaszczyzny sterowania, z wyjątkiem uprawnień zapytania)
    • Współautor (taki sam jak właściciel, z wyjątkiem uprawnień do przypisywania ról)
    • Czytelnik (akceptowalny w przypadku monitorowania i wyświetlania metryk)

  6. Na karcie Członkowie wybierz tożsamość użytkownika lub grupy firmy Microsoft Entra.

  7. Na karcie Przeglądanie i przypisywanie wybierz pozycję Przejrzyj i przypisz, aby przypisać rolę.

Przypisywanie ról do programowania

Przypisania ról są globalne w całej usłudze wyszukiwania. Aby ograniczyć zakres uprawnień do pojedynczego indeksu, użyj programu PowerShell lub interfejsu wiersza polecenia platformy Azure, aby utworzyć rolę niestandardową.

Inną kombinacją ról, które zapewniają pełny dostęp, jest Współautor lub Właściciel oraz Czytelnik danych indeksu wyszukiwania.

Ważne

W przypadku skonfigurowania dostępu opartego na rolach dla usługi lub indeksu i podania klucza interfejsu API w żądaniu usługa wyszukiwania używa klucza interfejsu API do uwierzytelniania.

  1. Zaloguj się w witrynie Azure Portal.

  2. Przejdź do usługi wyszukiwania.

  3. Wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami) w okienku nawigacji po lewej stronie.

  4. Wybierz pozycję + Dodaj>Dodaj przypisanie roli.

    Strona Kontrola dostępu (IAM) z otwartym menu Dodaj przypisanie roli.

  5. Wybierz rolę:

    • Współautor usługi wyszukiwania (operacje create-read-update-delete na indeksach, indeksatorach, zestawach umiejętności i innych obiektach najwyższego poziomu)
    • Współautor danych indeksu wyszukiwania (ładowanie dokumentów i uruchamianie zadań indeksowania)
    • Czytnik danych indeksu wyszukiwania (wykonywanie zapytań względem indeksu)

    Inną kombinacją ról, które zapewniają pełny dostęp, jest Współautor lub Właściciel oraz Czytelnik danych indeksu wyszukiwania.

  6. Na karcie Członkowie wybierz tożsamość użytkownika lub grupy firmy Microsoft Entra.

  7. Na karcie Przeglądanie i przypisywanie wybierz pozycję Przejrzyj i przypisz, aby przypisać rolę.

  8. Powtórz dla innych ról. Większość deweloperów potrzebuje wszystkich trzech.

Przypisywanie ról dla zapytań tylko do odczytu

Użyj roli Czytelnik danych indeksu wyszukiwania dla aplikacji i procesów, które wymagają tylko dostępu do odczytu do indeksu.

Jest to bardzo konkretna rola. Zapewnia dostęp GET lub POST do kolekcji dokumentów indeksu wyszukiwania na potrzeby wyszukiwania, autouzupełniania i sugestii. Nie obsługuje operacji GET lub LIST na indeksie lub innych obiektach najwyższego poziomu ani statystyk usługi GET.

Ta sekcja zawiera podstawowe kroki konfigurowania przypisania roli i znajduje się tutaj na potrzeby kompletności, ale zalecamy używanie usługi Azure AI Search bez kluczy , aby uzyskać kompleksowe instrukcje dotyczące konfigurowania aplikacji na potrzeby dostępu opartego na rolach.

  1. Zaloguj się w witrynie Azure Portal.

  2. Przejdź do usługi wyszukiwania.

  3. Wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami) w okienku nawigacji po lewej stronie.

  4. Wybierz pozycję + Dodaj>Dodaj przypisanie roli.

  5. Wybierz rolę Czytelnik danych indeksu wyszukiwania.

  6. Na karcie Członkowie wybierz tożsamość użytkownika lub grupy firmy Microsoft Entra. Jeśli konfigurujesz uprawnienia dla innej usługi, możesz użyć tożsamości systemowej lub zarządzanej przez użytkownika. Wybierz tę opcję, jeśli przypisanie roli dotyczy tożsamości usługi.

  7. Na karcie Przeglądanie i przypisywanie wybierz pozycję Przejrzyj i przypisz, aby przypisać rolę.

Testowanie przypisań ról

Użyj klienta do testowania przypisań ról. Należy pamiętać, że role są rolami zbiorczych i dziedziczonych, które są ograniczone do poziomu subskrypcji lub grupy zasobów, nie można usunąć ani odmówić na poziomie zasobu (usługi wyszukiwania).

Przed rozpoczęciem testowania skonfiguruj aplikację pod kątem połączeń bez kluczy i przypisań ról.

  1. Zaloguj się w witrynie Azure Portal.

  2. Przejdź do usługi wyszukiwania.

  3. Na stronie Przegląd wybierz kartę Indeksy :

    • Współautorzy usługi wyszukiwania mogą wyświetlać i tworzyć dowolny obiekt, ale nie mogą ładować dokumentów ani wykonywać zapytań dotyczących indeksu. Aby zweryfikować uprawnienia, utwórz indeks wyszukiwania.

    • Współautorzy danych indeksu wyszukiwania mogą ładować dokumenty. W portalu nie ma opcji ładowania dokumentów poza kreatorem importu danych, ale możesz zresetować i uruchomić indeksator, aby potwierdzić uprawnienia do ładowania dokumentu.

    • Czytelnicy danych indeksu wyszukiwania mogą wykonywać zapytania dotyczące indeksu. Aby zweryfikować uprawnienia, użyj Eksploratora wyszukiwania. Powinno być możliwe wysyłanie zapytań i wyświetlanie wyników, ale nie powinno być możliwe wyświetlenie definicji indeksu ani utworzenie go.

Testowanie jako bieżący użytkownik

Jeśli jesteś już współautorem lub właścicielem usługi wyszukiwania, możesz przedstawić token elementu nośnego dla tożsamości użytkownika na potrzeby uwierzytelniania w usłudze Azure AI Search.

  1. Pobierz token elementu nośnego dla bieżącego użytkownika przy użyciu interfejsu wiersza polecenia platformy Azure:

    az account get-access-token --scope https://search.azure.com/.default

    Lub przy użyciu programu PowerShell:

    Get-AzAccessToken -ResourceUrl https://search.azure.com

  2. Wklej te zmienne do nowego pliku tekstowego w programie Visual Studio Code.

    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@index-name = PASTE-YOUR-INDEX-NAME-HERE
@token = PASTE-YOUR-TOKEN-HERE

  3. Wklej polecenie , a następnie wyślij żądanie, aby potwierdzić dostęp. Oto jeden, który wykonuje zapytania dotyczące indeksu hotels-quickstart

    POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

    {
         "queryType": "simple",
         "search": "motel",
         "filter": "",
         "select": "HotelName,Description,Category,Tags",
         "count": true
     }

Udzielanie dostępu do pojedynczego indeksu

W niektórych scenariuszach możesz ograniczyć dostęp aplikacji do pojedynczego zasobu, takiego jak indeks.

Portal nie obsługuje obecnie przypisań ról na tym poziomie szczegółowości, ale można to zrobić za pomocą programu PowerShell lub interfejsu wiersza polecenia platformy Azure.

W programie PowerShell użyj polecenia New-AzRoleAssignment, podając nazwę użytkownika lub grupy platformy Azure oraz zakres przypisania.

  1. Załaduj Azure moduły i AzureAD i połącz się z kontem platformy Azure:

    Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount

  2. Dodaj przypisanie roli o zakresie do pojedynczego indeksu:

    New-AzRoleAssignment -ObjectId <objectId> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Tworzenie roli niestandardowej

Jeśli wbudowane role nie zapewniają odpowiedniej kombinacji uprawnień, możesz utworzyć rolę niestandardową do obsługi wymaganych operacji.

W tym przykładzie klonuje czytnik danych indeksu wyszukiwania, a następnie dodaje możliwość wyświetlania listy indeksów według nazwy. Zwykle wyświetlanie indeksów w usłudze wyszukiwania jest uznawane za prawo administracyjne.

Te kroki pochodzą z sekcji Tworzenie lub aktualizowanie ról niestandardowych platformy Azure przy użyciu witryny Azure Portal. Klonowanie z istniejącej roli jest obsługiwane na stronie usługi wyszukiwania.

Te kroki tworzą rolę niestandardową, która rozszerza prawa zapytań wyszukiwania w celu uwzględnienia indeksów listy według nazwy. Zazwyczaj lista indeksów jest traktowana jako funkcja administracyjna.

  1. W witrynie Azure Portal przejdź do usługi wyszukiwania.

  2. W okienku nawigacji po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).

  3. Na pasku akcji wybierz pozycję Role.

  4. Kliknij prawym przyciskiem myszy pozycję Search Index Data Reader (lub inną rolę) i wybierz polecenie Clone (Klonuj ), aby otworzyć kreatora Tworzenie roli niestandardowej.

  5. Na karcie Podstawy podaj nazwę roli niestandardowej, na przykład "Search Index Data Explorer", a następnie wybierz przycisk Dalej.

  6. Na karcie Uprawnienia wybierz pozycję Dodaj uprawnienie.

  7. Na karcie Dodawanie uprawnień wyszukaj, a następnie wybierz kafelek Microsoft Search .

  8. Ustaw uprawnienia dla roli niestandardowej. W górnej części strony użyj domyślnego wyboru Akcje :

    • W obszarze Microsoft.Search/operations wybierz pozycję Odczyt: Wyświetl wszystkie dostępne operacje.
    • W obszarze Microsoft.Search/searchServices/indexes wybierz pozycję Odczyt: Odczyt indeksu.

  9. Na tej samej stronie przejdź do pozycji Akcje danych i w obszarze Microsoft.Search/searchServices/indexes/documents wybierz pozycję Odczyt: Odczytaj dokumenty.

    Definicja JSON wygląda podobnie do poniższego przykładu:

    {
 "properties": {
     "roleName": "search index data explorer",
     "description": "",
     "assignableScopes": [
         "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
     ],
     "permissions": [
         {
             "actions": [
                 "Microsoft.Search/operations/read",
                 "Microsoft.Search/searchServices/indexes/read"
             ],
             "notActions": [],
             "dataActions": [
                 "Microsoft.Search/searchServices/indexes/documents/read"
             ],
             "notDataActions": []
         }
     ]
   }
 }

  10. Wybierz pozycję Przejrzyj i utwórz , aby utworzyć rolę. Teraz możesz przypisać użytkowników i grupy do roli.

Dostęp warunkowy

Zalecamy dostęp warunkowy firmy Microsoft Entra, jeśli musisz wymusić zasady organizacji, takie jak uwierzytelnianie wieloskładnikowe.

Aby włączyć zasady dostępu warunkowego dla usługi Azure AI Search, wykonaj następujące kroki:

  1. Zaloguj się do witryny Azure Portal.

  2. Wyszukaj pozycję Dostęp warunkowy firmy Microsoft Entra.

  3. Wybierz pozycję Zasady.

  4. Wybierz pozycję Nowe zasady.

  5. W sekcji Aplikacje w chmurze lub akcje zasad dodaj usługę Azure AI Search jako aplikację w chmurze w zależności od sposobu konfigurowania zasad.

  6. Zaktualizuj pozostałe parametry zasad. Na przykład określ użytkowników i grupy, do których mają zastosowanie te zasady.

  7. Zapisz zasady.

Ważne

Jeśli usługa wyszukiwania ma przypisaną tożsamość zarządzaną, określona usługa wyszukiwania będzie wyświetlana jako aplikacja w chmurze, która może zostać dołączona lub wykluczona w ramach zasad dostępu warunkowego. Nie można wymusić zasad dostępu warunkowego w określonej usłudze wyszukiwania. Zamiast tego upewnij się, że wybrano ogólną aplikację usługi Azure AI Search w chmurze.

Ograniczenia

  • Kontrola dostępu oparta na rolach może zwiększyć opóźnienie niektórych żądań. Każda unikatowa kombinacja zasobu usługi (indeks, indeksator itp.) i jednostka usługi wyzwala sprawdzanie autoryzacji. Te kontrole autoryzacji mogą składać się z maksymalnie 200 milisekund opóźnienia na żądanie.

  • W rzadkich przypadkach, w których żądania pochodzą z dużej liczby różnych jednostek usługi, wszystkie przeznaczone dla różnych zasobów usługi (indeksy, indeksatory itp.), możliwe jest sprawdzenie autoryzacji w celu ograniczenia przepustowości. Ograniczanie przepustowości miałoby miejsce tylko wtedy, gdy w ciągu sekundy użyto setek unikatowych kombinacji zasobu usługi wyszukiwania i jednostki usługi.

Rozwiązywanie problemów z kontrolą dostępu opartą na rolach

Podczas tworzenia aplikacji korzystających z kontroli dostępu opartej na rolach do uwierzytelniania mogą wystąpić niektóre typowe problemy:

  • Jeśli token autoryzacji pochodzi z tożsamości zarządzanej i zostały niedawno przypisane odpowiednie uprawnienia, może upłynąć kilka godzin, aby te przypisania uprawnień zaczęły obowiązywać.

  • Domyślną konfiguracją usługi wyszukiwania jest uwierzytelnianie oparte na kluczach. Jeśli ustawienie klucza domyślnego nie zostało zmienione na Zarówno , jak i Kontrola dostępu oparta na rolach, wszystkie żądania korzystające z uwierzytelniania opartego na rolach są automatycznie odrzucane niezależnie od podstawowych uprawnień.