Włączanie lub wyłączanie kontroli dostępu opartej na rolach w usłudze Azure AI Search

Usługa Azure AI Search domyślnie używa uwierzytelniania opartego na kluczach, ale w pełni obsługuje uwierzytelnianie i autoryzację identyfikatora Entra firmy Microsoft dla wszystkich operacji płaszczyzny sterowania i płaszczyzny danych za pośrednictwem kontroli dostępu opartej na rolach (RBAC) platformy Azure.

Aby można było przypisać role dostępu autoryzowanej płaszczyzny danych do usługi Azure AI Search, musisz włączyć kontrolę dostępu opartą na rolach w usłudze wyszukiwania. Role administracji usługą (płaszczyzny sterowania) są wbudowane i nie można ich włączyć ani wyłączyć.

Uwaga

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.

Wymagania wstępne

• Usługa wyszukiwania w dowolnym regionie, w dowolnej warstwie, w tym bezpłatna.

• Właściciel, administrator dostępu użytkowników lub rola niestandardowa z uprawnieniami Microsoft.Authorization/roleAssignments/write .

Włączanie dostępu opartego na rolach dla operacji płaszczyzny danych

Skonfiguruj usługę wyszukiwania, aby rozpoznać nagłówek autoryzacji dla żądań danych, które zapewniają token dostępu OAuth2.

Po włączeniu ról dla płaszczyzny danych zmiana jest skuteczna natychmiast, ale poczekaj kilka sekund przed przypisaniem ról.

Domyślnym trybem niepowodzenia dla nieautoryzowanych żądań jest http401WithBearerChallenge. Alternatywnie można ustawić tryb awarii na http403.

Witryna Azure Portal

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

2. Wybierz pozycję Ustawienia , a następnie wybierz pozycję Klucze w okienku nawigacji po lewej stronie.

   

3. Wybierz pozycję Kontrola oparta na rolach lub Obie , jeśli obecnie używasz kluczy i potrzebujesz czasu na przeniesienie klientów do kontroli dostępu opartej na rolach.

   Opcja	Opis
   Klucz interfejsu API	(wartość domyślna). Wymaga kluczy interfejsu API w nagłówku żądania na potrzeby autoryzacji.
   Kontrola dostępu oparta na rolach	Wymaga członkostwa w przypisaniu roli w celu ukończenia zadania. Wymaga również nagłówka autoryzacji w żądaniu.
   Oba	Żądania są prawidłowe przy użyciu klucza interfejsu API lub kontroli dostępu opartej na rolach, ale jeśli podasz oba te żądania, używany jest klucz interfejsu API.

4. Jako administrator, jeśli wybierzesz podejście tylko do ról, przypisz role płaszczyzny danych do konta użytkownika, aby przywrócić pełny dostęp administracyjny do operacji płaszczyzny danych w witrynie Azure Portal. Role obejmują współautora usługi wyszukiwania, współautora danych indeksu wyszukiwania i czytnika danych indeksu wyszukiwania. Potrzebujesz wszystkich trzech ról, jeśli chcesz uzyskać równoważny dostęp.

   Czasami może upłynąć od pięciu do dziesięciu minut, aby przypisania ról zaczęły obowiązywać. Do tego czasu na stronach portalu używanych na potrzeby operacji płaszczyzny danych zostanie wyświetlony następujący komunikat.

   

Interfejs wiersza polecenia platformy Azure

Uruchom ten skrypt, aby obsługiwać tylko role:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

Możesz też uruchomić ten skrypt, aby obsługiwać zarówno klucze, jak i role:

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --aad-auth-failure-mode http401WithBearerChallenge `
  --auth-options aadOrApiKey

Aby uzyskać więcej informacji, zobacz Zarządzanie usługa wyszukiwania usługi Azure AI przy użyciu interfejsu wiersza polecenia platformy Azure.

Azure PowerShell

Uruchom to polecenie, aby ustawić typ uwierzytelniania tylko na role:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

Możesz też uruchomić to polecenie, aby obsługiwać zarówno klucze, jak i role:

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -AuthOption AadOrApiKey

Aby uzyskać więcej informacji, zobacz Manage your Azure AI usługa wyszukiwania with PowerShell (Zarządzanie usługa wyszukiwania azure AI przy użyciu programu PowerShell).

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

Wyłączanie kontroli dostępu opartej na rolach

Można wyłączyć kontrolę dostępu opartą na rolach dla operacji płaszczyzny danych i użyć uwierzytelniania opartego na kluczach. Możesz to zrobić w ramach testowego przepływu pracy, na przykład w celu wykluczenia problemów z uprawnieniami.

Cofnięć kroki, które zostały wcześniej zastosowane, aby włączyć dostęp oparty na rolach.

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

2. Wybierz pozycję Ustawienia , a następnie wybierz pozycję Klucze w okienku nawigacji po lewej stronie.

3. Wybierz pozycję Klucze interfejsu API.

Wyłączanie uwierzytelniania klucza interfejsu API

Dostęp do klucza lub uwierzytelnianie lokalne można wyłączyć w usłudze, jeśli korzystasz wyłącznie z wbudowanych ról i uwierzytelniania firmy 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.

Klucze interfejsu API administratora można wyłączyć, ale nie można ich usunąć. Klucze interfejsu API zapytań można usunąć.

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

Witryna Azure 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 wiersza polecenia platformy Azure

Aby wyłączyć uwierzytelnianie oparte na kluczach, ustaw wartość -disableLocalAuth na wartość true. Jest to taka sama składnia jak skrypt "włącz tylko role" przedstawiony w poprzedniej sekcji.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

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

Aby uzyskać więcej informacji, zobacz Zarządzanie usługa wyszukiwania usługi Azure AI przy użyciu interfejsu wiersza polecenia platformy Azure.

Azure PowerShell

Aby wyłączyć uwierzytelnianie oparte na kluczach, ustaw wartość DisableLocalAuth na true. Jest to taka sama składnia jak skrypt "włącz tylko role" przedstawiony w poprzedniej sekcji.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

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

Aby uzyskać więcej informacji, zobacz Manage your Azure AI usługa wyszukiwania with PowerShell (Zarządzanie usługa wyszukiwania azure AI przy użyciu programu PowerShell).

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 ustawia 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
       }
   }
   

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

Efekty kontroli dostępu opartej na rolach

• Kontrola dostępu oparta na rolach może zwiększyć opóźnienie niektórych żądań. Każda unikatowa kombinacja zasobu usługi (indeks, indeksator, zestawy umiejętności itd.) 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, gdy żądania pochodzą z dużej liczby różnych jednostek usługi, wszystkie przeznaczone dla różnych zasobów usługi (indeksy, indeksatory i tak dalej), można sprawdzić autoryzację 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.

Następne kroki

Konfigurowanie ról na potrzeby dostępu do usługi wyszukiwania