Połączenie do usługi Azure AI Search przy użyciu kontroli dostępu opartej na rolach

Platforma Azure udostępnia globalny system autoryzacji kontroli dostępu opartej na rolach dla wszystkich usług uruchomionych na platformie. W usłudze Azure AI Search możesz użyć ról platformy Azure dla:

• Operacje płaszczyzny sterowania (zadania administracyjne usługi za pośrednictwem usługi Azure Resource Manager).

• Operacje płaszczyzny danych, takie jak tworzenie, ładowanie i wykonywanie zapytań względem indeksów.

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

Uwaga

Krótka uwaga dotycząca terminologii. Płaszczyzna sterowania odnosi się do operacji obsługiwanych w interfejsie API REST zarządzania lub równoważnych bibliotekach klienta. 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 interfejsie API REST wyszukiwania lub równoważne biblioteki klienckie.

Wbudowane role używane w wyszukiwaniu

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

Rola	Płaszczyzny	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.

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.

Ograniczenia

• Przyjęcie kontroli dostępu opartej na rolach może zwiększyć opóźnienie niektórych żądań. Każda unikatowa kombinacja zasobu usługi (indeksu, indeksatora itp.) i jednostki usługi używanej w żądaniu wyzwala sprawdzanie autoryzacji. Te kontrole autoryzacji mogą dodawać do 200 milisekund opóźnienia do żądania.

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

Konfigurowanie dostępu opartego na rolach dla płaszczyzny danych

Dotyczy: Współautor danych indeksu wyszukiwania, Czytelnik danych indeksu wyszukiwania, Współautor usługi wyszukiwania

W tym kroku skonfiguruj usługę wyszukiwania, aby rozpoznała nagłówek autoryzacji dla żądań danych, które udostępniają token dostępu OAuth2.

Witryna Azure Portal

1. Zaloguj się do witryny Azure Portal i otwórz stronę usługi wyszukiwania.

2. Wybierz pozycję Klucze w okienku nawigacji po lewej stronie.

   

3. Wybierz opcję kontroli dostępu interfejsu API. Zalecamy obie opcje, jeśli chcesz elastycznie lub chcesz migrować aplikacje.

   Opcja	Opis
   Klucz interfejsu API	(wartość domyślna). Wymaga klucza interfejsu API administratora lub zapytania w nagłówku żądania na potrzeby autoryzacji. Nie są używane żadne role.
   Kontrola dostępu oparta na rolach	Wymaga członkostwa w przypisaniu roli w celu ukończenia zadania opisanego w następnym kroku. Wymaga również nagłówka autoryzacji.
   Oba	Żądania są prawidłowe przy użyciu klucza interfejsu API lub kontroli dostępu opartej na rolach.

Zmiana jest skuteczna natychmiast, ale poczekaj kilka sekund przed rozpoczęciem testowania.

Wszystkie wywołania sieciowe operacji usługi wyszukiwania i zawartości są zgodne z wybraną opcją: Klucze interfejsu API, token elementu nośnego lub jeden, jeśli wybierzesz opcję Oba.

Po włączeniu kontroli dostępu opartej na rolach w portalu tryb niepowodzenia to "http401WithBearerChallenge", jeśli autoryzacja zakończy się niepowodzeniem.

Interfejs API REST

Użyj interfejsu API REST zarządzania tworzeniem lub aktualizowaniem usługi , aby skonfigurować usługę na potrzeby kontroli dostępu opartej na rolach.

Wszystkie wywołania interfejsu API REST zarządzania są uwierzytelniane za pośrednictwem identyfikatora Entra firmy Microsoft z uprawnieniami współautora lub właściciela. Aby uzyskać pomoc dotyczącą konfigurowania uwierzytelnionych żądań, zobacz Zarządzanie usługą Azure AI Search przy użyciu interfejsu REST.

1. Pobierz ustawienia usługi, aby można było przejrzeć bieżącą konfigurację.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Użyj poprawki PATCH, aby zaktualizować konfigurację usługi. Następujące modyfikacje umożliwiają zarówno klucze, jak i dostęp oparty na rolach. Jeśli chcesz mieć konfigurację tylko do ról, zobacz Wyłączanie kluczy interfejsu API.

   W obszarze "properties" ustaw wartość "authOptions" na "aadOrApiKey". Właściwość "disableLocalAuth" musi mieć wartość false, aby ustawić wartość "authOptions".

   Opcjonalnie ustaw wartość "aadAuthFailureMode" , aby określić, czy wartość 401 jest zwracana zamiast 403 w przypadku niepowodzenia uwierzytelniania. Prawidłowe wartości to "http401WithBearerChallenge" lub "http403".

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": false,
           "authOptions": {
               "aadOrApiKey": {
                   "aadAuthFailureMode": "http401WithBearerChallenge"
               }
           }
       }
   }
   

3. Postępuj zgodnie z instrukcjami w następnym kroku, aby przypisać role dla operacji płaszczyzny danych.

Przypisywanie ról

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.

Aby zarządzać przypisaniami ról, musisz być właścicielem lub mieć uprawnienia Microsoft.Authorization/roleAssignments/write.

Witryna Azure Portal

Przypisania ról w portalu są dla całej usługi. Jeśli chcesz udzielić uprawnień do pojedynczego indeksu, zamiast tego użyj programu PowerShell lub interfejsu wiersza polecenia platformy Azure.

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
   • Współautor
   • Czytelnik
   • Współautor usługi wyszukiwania
   • Współautor danych indeksu wyszukiwania
   • Czytnik 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ę.

Program PowerShell

W przypadku przypisywania ról przy użyciu programu PowerShell wywołaj polecenie New-AzRoleAssignment, podając nazwę użytkownika lub grupy platformy Azure oraz zakres przypisania.

Przed rozpoczęciem upewnij się, że moduły Az i AzureAD łączą się z platformą Azure:

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

W tym przykładzie utworzono przypisanie roli o zakresie do usługi wyszukiwania:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

W tym przykładzie utworzono przypisanie roli o określonym zakresie do określonego indeksu:

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

Pamiętaj, że dostęp do zasobów najwyższego poziomu można ograniczyć tylko do zakresu, takich jak indeksy, mapy synonimów, indeksatory, źródła danych i zestawy umiejętności. Nie można kontrolować dostępu do dokumentów wyszukiwania (zawartości indeksu) przy użyciu ról platformy Azure.

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ą objęte zakresem subskrypcji lub grupy zasobów, nie można usunąć ani odmówić na poziomie zasobu (usługi wyszukiwania).

Przed przetestowaniem dostępu upewnij się, że aplikacja kliencka jest zarejestrowana w usłudze Microsoft Entra ID i masz przypisanie ról.

Witryna Azure Portal

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ć i wykonywać zapytania dotyczące dokumentów. Aby zweryfikować uprawnienia, użyj Eksploratora wyszukiwania do wykonywania zapytań dotyczących dokumentów. W portalu nie ma opcji ładowania dokumentów poza kreatorem importu danych. Ponieważ kreator tworzy również obiekty, potrzebny będzie współautor usługi wyszukiwania oraz współautor danych indeksu wyszukiwania.

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

Interfejs API REST

W tym podejściu przyjęto założenie, że program Visual Studio Code z rozszerzeniem klienta REST.

1. Otwórz powłokę poleceń dla interfejsu wiersza polecenia platformy Azure i zaloguj się do subskrypcji platformy Azure.

   az login
   

2. Pobierz identyfikator dzierżawy i identyfikator subskrypcji. Identyfikator jest używany jako zmienna w przyszłym kroku.

   az account show
   

3. Uzyskiwanie tokenu dostępu.

   az account get-access-token --query accessToken --output tsv
   

4. W nowym pliku tekstowym w programie Visual Studio Code wklej następujące zmienne:

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

5. Wklej i wyślij żądanie, które używa określonych zmiennych. Dla roli "Czytelnik danych indeksu wyszukiwania" możesz wysłać zapytanie. Możesz użyć dowolnej obsługiwanej wersji interfejsu API.

   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
        }
   

Aby uzyskać więcej informacji na temat uzyskiwania tokenu dla określonego środowiska, zobacz Manage a Azure AI usługa wyszukiwania with REST APIs and Platforma tożsamości Microsoft authentication libraries (Zarządzanie usługą Azure AI usługa wyszukiwania przy użyciu interfejsów API REST i bibliotek uwierzytelniania Platforma tożsamości Microsoft).

.NET

1. Użyj pakietu Azure.Search.Documents.

2. Użyj usługi Azure.Identity dla platformy .NET na potrzeby uwierzytelniania tokenu. Firma Microsoft zaleca DefaultAzureCredential() korzystanie z większości scenariuszy.

3. Oto przykład połączenia klienta przy użyciu polecenia DefaultAzureCredential().

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

4. Oto kolejny przykład użycia poświadczeń wpisu tajnego klienta:

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

Python

1. Użyj azure.search.documents (zestaw Azure SDK dla języka Python).

2. Użyj usługi Azure.Identity dla języka Python na potrzeby uwierzytelniania tokenów.

3. Użyj wartości DefaultAzureCredential , jeśli klient języka Python jest aplikacją, która wykonuje po stronie serwera. Włącz uwierzytelnianie interakcyjne, jeśli aplikacja działa w przeglądarce.

4. Oto przykład:

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

JavaScript

1. Użyj @azure/search-documents (Zestaw Azure SDK dla języka JavaScript), wersja 11.3.

2. Użyj usługi Azure.Identity dla języka JavaScript na potrzeby uwierzytelniania tokenu.

3. Jeśli używasz platformy React, użyj InteractiveBrowserCredential uwierzytelniania Microsoft Entra do wyszukiwania. Zobacz Kiedy używać @azure/identity , aby uzyskać szczegółowe informacje.

Java

1. Użyj usługi azure-search-documents (zestawu Azure SDK dla języka Java).

2. Użyj elementu Azure.Identity dla języka Java na potrzeby uwierzytelniania tokenu.

3. Firma Microsoft zaleca ustawienie DefaultAzureCredential dla aplikacji uruchamianych na platformie Azure.

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. W nowym pliku tekstowym w programie Visual Studio Code wklej następujące zmienne:

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

Azure Portal

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.

Azure PowerShell

W przykładzie programu PowerShell przedstawiono składnię JSON do tworzenia roli niestandardowej, która jest klonem czytnika danych indeksu wyszukiwania, ale z możliwością wyświetlania listy wszystkich indeksów według nazwy.

1. Przejrzyj listę niepodzielnych uprawnień, aby określić, które z nich potrzebujesz. W tym przykładzie potrzebne są następujące elementy:

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. Skonfiguruj sesję programu PowerShell, aby utworzyć rolę niestandardową. Aby uzyskać szczegółowe instrukcje, zobacz Azure PowerShell

3. Podaj definicję roli jako dokument JSON. Poniższy przykład przedstawia składnię tworzenia roli niestandardowej za pomocą programu PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

Uwaga

Jeśli zakres możliwy do przypisania znajduje się na poziomie indeksu, akcja danych powinna mieć wartość "Microsoft.Search/searchServices/indexes/documents/read".

Interfejs API REST

1. Przejrzyj listę niepodzielnych uprawnień, aby określić, które z nich potrzebujesz.

2. Aby uzyskać instrukcje, zobacz Tworzenie lub aktualizowanie ról niestandardowych platformy Azure przy użyciu interfejsu API REST.

3. Sklonuj lub utwórz rolę albo użyj formatu JSON, aby określić rolę niestandardową (zobacz kartę programu PowerShell dla składni JSON).

Interfejs wiersza polecenia platformy Azure

1. Przejrzyj listę niepodzielnych uprawnień, aby określić, które z nich potrzebujesz.

2. Aby uzyskać instrukcje, zobacz Tworzenie lub aktualizowanie ról niestandardowych platformy Azure przy użyciu interfejsu wiersza polecenia platformy Azure.

3. Sklonuj lub utwórz rolę albo użyj formatu JSON, aby określić rolę niestandardową (zobacz kartę programu PowerShell dla składni JSON).

Wyłączanie uwierzytelniania klucza interfejsu API

Dostęp do klucza lub uwierzytelnianie lokalne można wyłączyć w usłudze, jeśli używasz ról Współautor usługi wyszukiwania, Współautor danych indeksu wyszukiwania i Czytelnik danych indeksu wyszukiwania oraz uwierzytelnianie Microsoft Entra. Wyłączenie kluczy interfejsu API powoduje, że usługa wyszukiwania odrzuca wszystkie żądania związane z danymi, które przekazują klucz interfejsu API w nagłówku.

Uwaga

Administracja klucze interfejsu API można wyłączyć tylko, a nie usunąć. Klucze interfejsu API zapytań można usunąć.

Uprawnienia właściciela lub współautora są wymagane do wyłączenia funkcji.

Aby wyłączyć uwierzytelnianie oparte na kluczach, użyj witryny Azure Portal lub interfejsu API REST zarządzania.

Portal

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

2. W okienku nawigacji po lewej stronie wybierz pozycję Klucze.

3. Wybierz pozycję Kontrola dostępu oparta na rolach.

Zmiana jest skuteczna natychmiast, ale poczekaj kilka sekund przed rozpoczęciem testowania. Zakładając, że masz uprawnienia do przypisywania ról jako członek właściciela, administratora usługi lub współadministratora, możesz użyć funkcji portalu do testowania dostępu opartego na rolach.

Interfejs API REST

Aby wyłączyć uwierzytelnianie oparte na kluczach, ustaw wartość "disableLocalAuth" na true.

1. Pobierz ustawienia usługi, aby można było przejrzeć bieżącą konfigurację.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Użyj poprawki PATCH, aby zaktualizować konfigurację usługi. Poniższa modyfikacja ustawi wartość "authOptions" na wartość null.

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": true
       }
   }
   

Żądania zawierające tylko klucz interfejsu API bez tokenu elementu nośnego kończą się niepowodzeniem z protokołem HTTP 401.

Aby ponownie włączyć uwierzytelnianie klucza, uruchom ponownie ostatnie żądanie, ustawiając wartość "disableLocalAuth" na false. Usługa wyszukiwania wznawia akceptację kluczy interfejsu API w żądaniu automatycznie (przy założeniu, że zostały określone).

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.

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 tylko 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ń.