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

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 pozycję Kontrola oparta na rolach lub Obie , jeśli chcesz mieć elastyczność.

   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.

Zmiana jest skuteczna natychmiast, ale poczekaj kilka sekund przed przypisaniem ról.

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

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

Zmiana jest skuteczna natychmiast, ale poczekaj kilka sekund przed przypisaniem ról.

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

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

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.

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

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

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ę:

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

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.

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

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

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.

1. Pobierz identyfikator subskrypcji, grupę zasobów usługi wyszukiwania i nazwę usługi wyszukiwania.

2. Pobierz identyfikator obiektu usługi platformy Azure, taki jak Azure OpenAI.

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. Pobierz definicję roli i przejrzyj uprawnienia, aby upewnić się, że jest to odpowiednia rola.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. Utwórz przypisanie roli, podstawiając prawidłowe wartości dla symboli zastępczych.

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME
   

5. Oto przykład przypisania roli o określonym zakresie do określonego indeksu:

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME
   

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.

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

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

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)
   

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.

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.

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.

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

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

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

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.

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