Autoryzowanie dostępu do aplikacji wyszukiwania przy użyciu identyfikatora Entra firmy Microsoft

Aplikacje wyszukiwania oparte na usłudze Azure AI Search mogą teraz używać Platforma tożsamości Microsoft do uwierzytelnionego i autoryzowanego dostępu. Na platformie Azure dostawca tożsamości to Microsoft Entra ID. Kluczową zaletą korzystania z identyfikatora Entra firmy Microsoft jest to, że poświadczenia i klucze interfejsu API nie muszą już być przechowywane w kodzie. Firma Microsoft Entra uwierzytelnia podmiot zabezpieczeń (użytkownika, grupy lub usługi) uruchomionej aplikacji. Jeśli uwierzytelnianie powiedzie się, identyfikator Entra firmy Microsoft zwraca token dostępu do aplikacji, a aplikacja może następnie użyć tokenu dostępu do autoryzowania żądań do usługi Azure AI Search.

W tym artykule pokazano, jak skonfigurować klienta dla identyfikatora Entra firmy Microsoft:

• Na potrzeby uwierzytelniania utwórz tożsamość zarządzaną dla aplikacji. Możesz użyć innego typu obiektu podmiotu zabezpieczeń, ale w tym artykule są używane tożsamości zarządzane, ponieważ eliminują one konieczność zarządzania poświadczeniami.

• Aby uzyskać autoryzację, przypisz rolę platformy Azure do tożsamości zarządzanej, która przyznaje uprawnienia do uruchamiania zapytań lub zarządzania zadaniami indeksowania.

• Zaktualizuj kod klienta, aby wywołać metodę TokenCredential(). Możesz na przykład rozpocząć pracę z nowym elementem SearchClient(endpoint, new DefaultAzureCredential()), aby uwierzytelnić się za pomocą identyfikatora Entra firmy Microsoft przy użyciu elementu Azure.Identity.

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	(ustawienie domyślne) 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

Skonfiguruj usługę przy użyciu interfejsu API REST zarządzania tworzeniem lub aktualizowaniem usługi .

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ń w kliencie REST, 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"
               }
           }
       }
   }
   

Tworzenie tożsamości zarządzanej

W tym kroku utwórz tożsamość zarządzaną dla aplikacji klienckiej.

1. Zaloguj się w witrynie Azure Portal.

2. Wyszukaj pozycję Tożsamości zarządzane.

3. Wybierz pozycję Utwórz.

4. Nadaj tożsamości zarządzanej nazwę i wybierz region. Następnie wybierz przycisk Utwórz.

   

Przypisywanie roli do tożsamości zarządzanej

Następnie należy udzielić tożsamości zarządzanej klienta dostępu do usługi wyszukiwania. Usługa Azure AI Search ma różne wbudowane role. Możesz również utworzyć rolę niestandardową.

Najlepszym rozwiązaniem jest przyznanie minimalnych uprawnień. Jeśli aplikacja musi obsługiwać tylko zapytania, należy przypisać rolę Czytelnik danych indeksu wyszukiwania. Alternatywnie, jeśli klient potrzebuje zarówno dostępu do odczytu, jak i zapisu w indeksie wyszukiwania, należy użyć roli Współautor danych indeksu wyszukiwania.

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

     Uwaga

     Współautor, Współautor, Czytelnik i Współautor usługi wyszukiwania to role płaszczyzny sterowania i nie zapewniają dostępu do danych w indeksie wyszukiwania. Aby uzyskać dostęp do danych, wybierz rolę Współautor danych indeksu wyszukiwania lub Czytelnik danych indeksu wyszukiwania. Aby uzyskać więcej informacji na temat zakresu i przeznaczenia każdej roli, zobacz Wbudowane role używane w wyszukiwaniu.

6. Na karcie Członkowie wybierz tożsamość zarządzaną, którą chcesz udzielić dostępu do usługi wyszukiwania.

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

Możesz przypisać wiele ról, takich jak Współautor usługi wyszukiwania i Współautor danych indeksu wyszukiwania, jeśli aplikacja potrzebuje kompleksowego dostępu do usług wyszukiwania, obiektów i zawartości.

Role można również przypisywać przy użyciu programu PowerShell.

Konfigurowanie uwierzytelniania w usłudze Microsoft Entra w kliencie

Po utworzeniu tożsamości zarządzanej i przypisania roli w usłudze wyszukiwania możesz dodać kod do aplikacji w celu uwierzytelnienia podmiotu zabezpieczeń i uzyskania tokenu OAuth 2.0.

Użyj następujących bibliotek klienckich do kontroli dostępu opartej na rolach:

• azure.search.documents (Zestaw Azure SDK dla platformy .NET)
• azure-search-documents (Zestaw Azure SDK dla języka Java)
• azure/search-documents (Zestaw Azure SDK dla języka JavaScript)
• azure.search.documents (Zestaw Azure SDK dla języka Python)

Uwaga

Aby dowiedzieć się więcej na temat przepływu udzielania kodu OAuth 2.0 używanego przez identyfikator entra firmy Microsoft, zobacz Autoryzowanie dostępu do aplikacji internetowych Firmy Microsoft Entra przy użyciu przepływu udzielania kodu OAuth 2.0.

Zestaw SDK platformy .NET

Poniższe instrukcje odwołują się do istniejącego przykładu w języku C#, aby zademonstrować zmiany kodu.

1. Jako punkt wyjścia sklonuj kod źródłowy sekcji przewodnika Szybki start: wyszukiwanie pełnotekstowe przy użyciu zestawów SDK platformy Azure.

   Przykład używa obecnie uwierzytelniania opartego na kluczach i AzureKeyCredential elementu , aby utworzyć SearchClient element i SearchIndexClient , ale możesz wprowadzić niewielką zmianę, aby przełączyć się na uwierzytelnianie oparte na rolach.

2. Zaktualizuj pakiet NuGet Azure.Search.Documents do wersji 11.4 lub nowszej.

3. Zaimportuj bibliotekę Azure.Identity , aby uzyskać dostęp do innych technik uwierzytelniania.

4. Zamiast używać AzureKeyCredential na początkuMain()Program.cs, użyj polecenia DefaultAzureCredential jak w poniższym fragmencie kodu:

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

Testowanie lokalne

Tożsamości zarządzane przypisane przez użytkownika działają tylko w środowiskach platformy Azure. Jeśli uruchomisz ten kod lokalnie, DefaultAzureCredential wróć do uwierzytelnienia przy użyciu poświadczeń. Upewnij się, że masz wymagany dostęp do usługi wyszukiwania, jeśli planujesz uruchomić kod lokalnie.

1. Sprawdź, czy twoje konto ma przypisania ról, aby uruchomić wszystkie operacje w przykładzie Szybki start. Aby utworzyć i utworzyć indeks, użyj opcji "Czytelnik danych indeksu wyszukiwania" i "Współautor danych indeksu wyszukiwania".

2. Przejdź do pozycji Narzędzia>Opcje>uwierzytelniania usługi platformy Azure, aby wybrać konto logowania platformy Azure.

Teraz powinno być możliwe uruchomienie projektu z programu Visual Studio w systemie lokalnym przy użyciu kontroli dostępu opartej na rolach na potrzeby autoryzacji.

Uwaga

Dokumentacja azure.Identity zawiera więcej szczegółowych informacji na temat DefaultAzureCredential uwierzytelniania firmy Microsoft i korzystania z usługi Microsoft Entra z zestawem Azure SDK dla platformy .NET. DefaultAzureCredential Ma na celu uproszczenie rozpoczynania pracy z zestawem SDK przez obsługę typowych scenariuszy z rozsądnymi zachowaniami domyślnymi. Deweloperzy, którzy chcą mieć większą kontrolę lub którego scenariusz nie jest obsługiwany przez ustawienia domyślne, powinni używać innych typów poświadczeń.

Interfejs API REST

Korzystanie z zestawu Azure SDK upraszcza przepływ protokołu OAuth 2.0, ale można również programować bezpośrednio względem protokołu w aplikacji. Pełne szczegóły są dostępne w Platforma tożsamości Microsoft i przepływ poświadczeń klienta OAuth 2.0.

1. Zacznij od pobrania tokenu z Platforma tożsamości Microsoft:

   POST /[tenant id]/oauth2/v2.0/token HTTP/1.1
   Host: login.microsoftonline.com
   Content-Type: application/x-www-form-urlencoded
   
   client_id=[client id]
   &scope=https%3A%2F%2Fsearch.azure.com%2F.default
   &client_secret=[client secret]
   &grant_type=client_credentials
   

   Wymagany zakres to "https://search.azure.com/.default".

2. Teraz, gdy masz token, możesz wysłać żądanie do usługi wyszukiwania.

   GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters]
   Content-Type: application/json   
   Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
   

Zobacz też

• Korzystanie z kontroli dostępu opartej na rolach platformy Azure w usłudze Azure AI Search
• Autoryzowanie dostępu do aplikacji internetowych firmy Microsoft Entra przy użyciu przepływu udzielania kodu OAuth 2.0
• Integrowanie z identyfikatorem Entra firmy Microsoft
• Role niestandardowe platformy Azure