Udostępnij za pośrednictwem


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

Platforma Azure zapewnia globalne uwierzytelnianie i kontrolę dostępu opartą na rolach za pośrednictwem identyfikatora Entra firmy Microsoft dla wszystkich usług uruchomionych na platformie. W tym artykule dowiesz się, które role zapewniają dostęp do wyszukiwania zawartości i administracji w usłudze Azure AI Search.

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

Jak przypisywać role w witrynie Azure Portal

Poniższe kroki działają dla wszystkich przypisań ról.

  1. Zaloguj się w witrynie Azure Portal.

  2. Przejdź do usługi wyszukiwania.

  3. Włącz dostęp oparty na rolach.

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

  5. Wybierz pozycję + Dodaj>przypisanie roli, aby uruchomić Kreatora dodawania przypisania roli.

    Zrzut ekranu przedstawiający stronę kontroli dostępu w witrynie Azure Portal.

  6. Wybierz rolę. Można przypisać wiele podmiotów zabezpieczeń, niezależnie od tego, czy użytkownicy, czy tożsamości zarządzane do roli w jednym przekazaniu kreatora, ale musisz powtórzyć te kroki dla każdej zdefiniowanej roli.

  7. Na karcie Członkowie wybierz tożsamość użytkownika lub grupy firmy Microsoft Entra. Jeśli konfigurujesz uprawnienia dla innej usługi platformy Azure, wybierz tożsamość systemową lub zarządzaną przez użytkownika.

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

Płaszczyzna danych odnosi się do operacji względem punktu końcowego usługi wyszukiwania, takiego jak indeksowanie lub zapytania, lub dowolna inna operacja określona w interfejsach API REST usługi wyszukiwania lub równoważne biblioteki klienta zestawu Azure SDK.

Płaszczyzna sterowania odnosi się do zarządzania zasobami platformy Azure, takich jak tworzenie lub konfigurowanie usługi wyszukiwania.

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.

Podsumowanie

Uprawnienia Czytnik danych indeksu wyszukiwania Współautor danych indeksu wyszukiwania Współautor usługi wyszukiwania Właściciel/współautor Czytelnik
Wyświetlanie zasobu w witrynie Azure Portal
Wyświetlanie właściwości zasobu/metryk/punktu końcowego
Wyświetlanie listy wszystkich obiektów w zasobie
Limity przydziału dostępu i statystyki usługi
Odczytywanie/wykonywanie zapytań względem indeksu
Przekazywanie danych do indeksowania
Tworzenie lub edytowanie indeksów/aliasów
Tworzenie, edytowanie i uruchamianie indeksatorów/źródeł danych/zestawów umiejętności
Tworzenie lub edytowanie map synonimów
Tworzenie lub edytowanie sesji debugowania
Tworzenie wdrożeń lub zarządzanie nimi
Tworzenie lub konfigurowanie zasobów usługi Azure AI Search
Wyświetlanie/kopiowanie/ponowne generowanie kluczy w obszarze Klucze
Wyświetlanie ról/zasad/definicji
Ustawianie opcji uwierzytelniania
Konfigurowanie połączeń prywatnych
Konfigurowanie zabezpieczeń sieci

Właściciele i współautorzy przyznają te same uprawnienia, z wyjątkiem tego, że tylko właściciele mogą przypisywać role.

Właściciele i współautorzy mogą tworzyć, odczytywać, aktualizować i usuwać obiekty w witrynie Azure Portal , jeśli są włączone klucze interfejsu API. Witryna Azure Portal używa kluczy w przypadku wewnętrznych wywołań interfejsów API płaszczyzny danych. Następnie skonfigurujesz usługę Azure AI Search tak, aby korzystała tylko z ról, a następnie właściciel i współautor nie będą mogli zarządzać obiektami w witrynie Azure Portal przy użyciu tylko tych przypisań ról. Rozwiązaniem jest przypisanie większej liczby ról, takich jak czytelnik danych indeksu wyszukiwania, współautor danych indeksu wyszukiwania i współautor usługi wyszukiwania.

Przypisywanie ról

W tej sekcji przypisz role dla:

  • Administrowanie usługą
  • Tworzenie lub zapisywanie dostępu do usługi wyszukiwania
  • Dostęp tylko do odczytu dla zapytań

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. Jeśli jesteś właścicielem lub współautorem, możesz również wykonywać większość zadań interfejsu API REST wyszukiwania płaszczyzny danych w witrynie Azure Portal.

Rola ID
Owner 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor b24988ac-6180-42a0-ab88-20f7382dd24c
Reader acdd72a7-3385-48ef-bd42-f606fba81ae7
  1. Zaloguj się w witrynie Azure Portal.

  2. Przypisz następujące role:

    • 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)

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ą.

Zadanie Rola ID
Operacje CRUD Search Service Contributor 7ca78c08-252a-4471-8644-bb5ff32d4ba0
Ładowanie dokumentów, uruchamianie zadań indeksowania Search Index Data Contributor 8ebe5a00-799e-43f5-93ac-243d3dce84a7
Wykonywanie zapytań względem indeksu Search Index Data Reader 1407120a-92aa-4202-b7e9-c0e197c71c8f

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. Przypisz następujące role:

    • 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)

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.

Rola ID
Search Index Data Readerza pomocą programu PowerShell 1407120a-92aa-4202-b7e9-c0e197c71c8f

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. Przypisz rolę Czytelnik danych indeksu wyszukiwania.

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 witrynie Azure Portal 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=2024-07-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.

Witryna Azure 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ń.