Авторизация доступа к приложению поиска с помощью идентификатора Microsoft Entra

Теперь приложения поиска, созданные на основе поиска ИИ Azure, могут использовать платформа удостоверений Майкрософт для проверки подлинности и авторизованного доступа. В Azure поставщик удостоверений — это идентификатор Microsoft Entra. Ключевым преимуществом использования идентификатора Microsoft Entra является то, что учетные данные и ключи API больше не должны храниться в коде. Microsoft Entra проверяет подлинность субъекта безопасности (пользователя, группы или службы), выполняющих приложение. Если проверка подлинности выполнена успешно, идентификатор Microsoft Entra возвращает маркер доступа к приложению, а приложение может использовать маркер доступа для авторизации запросов в службе "Поиск ИИ Azure".

В этой статье показано, как настроить клиент для идентификатора Microsoft Entra:

• Для проверки подлинности создайте управляемое удостоверение для приложения. Вы можете использовать другой тип объекта субъекта безопасности, но в этой статье используются управляемые удостоверения, так как они устраняют необходимость управления учетными данными.

• Для авторизации назначьте роль Azure управляемому удостоверению, которое предоставляет разрешения на выполнение запросов или управление заданиями индексирования.

• Обновите код клиента для вызова TokenCredential(). Например, вы можете приступить к работе с новым searchClient(endpoint, new DefaultAzureCredential()) для проверки подлинности с помощью идентификатора Microsoft Entra с помощью Azure.Identity.

Настройка доступа на основе ролей для плоскости данных

Область применения: участник данных индекса поиска, средство чтения индексов поиска, участник службы поиска

На этом шаге настройте службу поиска для распознавания заголовка авторизации по запросам данных, которые предоставляют маркер доступа OAuth2.

Портал Azure

1. Войдите в портал Azure и откройте страницу службы поиска.

2. В расположенной слева области навигации щелкните Ключи.

   

3. Выберите параметр управления доступом API. Рекомендуется использовать оба варианта, если требуется гибкость или необходимость переноса приложений.

   Вариант	Описание
   Ключ API	(по умолчанию) Требуется ключи API администратора или запроса в заголовке запроса для авторизации. Роли не используются.
   Управление доступом на основе ролей	Для выполнения задач, описанных в следующем действии, требуются привилегии по назначению ролей. Кроме того, требуется заголовок авторизации.
   Оба	Запросы действительны с помощью ключа API или управления доступом на основе ролей.

Изменение действует немедленно, но подождите несколько секунд до тестирования.

Все сетевые вызовы для операций службы поиска и содержимого учитывают выбранное значение: ключи API, маркер носителя или один, если выбрать оба.

При включении управления доступом на основе ролей на портале режим сбоя — http401WithBearerChallenge, если авторизация завершается ошибкой.

REST API

Чтобы настроить службу, используйте REST API управления для создания или обновления службы.

Все вызовы REST API управления проходят проверку подлинности с помощью идентификатора Microsoft Entra с разрешениями участника или владельца. Сведения о настройке прошедших проверку подлинности запросов в клиенте REST см. в статье "Управление поиском ИИ Azure с помощью REST".

1. Получите параметры службы, чтобы просмотреть текущую конфигурацию.

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

2. Используйте PATCH для обновления конфигурации службы. Следующие изменения позволяют использовать ключи и доступ на основе ролей. Если требуется конфигурация только для ролей, см. раздел "Отключить ключи API".

   В разделе "Свойства" задайте для параметра authOptions значение aadOrApiKey. Свойство disableLocalAuth должно иметь значение false, чтобы задать authOptions.

   При необходимости задайте параметр aadAuthFailureMode , чтобы указать, возвращается ли 401 вместо 403 при сбое проверки подлинности. Допустимые значения: http401WithBearerChallenge или 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"
               }
           }
       }
   }
   

Создание управляемого удостоверения

На этом шаге создайте управляемое удостоверение для клиентского приложения.

1. Войдите на портал Azure.

2. Поиск управляемых удостоверений.

3. Нажмите кнопку создания.

4. Присвойте управляемому удостоверению имя и выберите регион. Затем выберите Создать.

   

Назначение роли управляемому удостоверению

Затем необходимо предоставить управляемому удостоверению клиента доступ к службе поиска. Поиск по искусственному интеллекту Azure имеет различные встроенные роли. Вы также можете создать настраиваемую роль.

Рекомендуется предоставить минимальные разрешения. Если приложению требуется обрабатывать только запросы, следует назначить роль средства чтения индексов поиска. Кроме того, если клиенту требуется доступ на чтение и запись в индексе поиска, следует использовать роль участника данных индекса поиска.

1. Войдите на портал Azure.

2. Перейдите к своей службе поиска

3. Выберите элемент управления доступом (IAM) в области навигации слева.

4. Выберите + Добавить>Добавить назначение ролей.

   

5. Выберите соответствующую роль:

   • Владелец

   • Участник

   • Читатель

   • Участник службы поиска

   • Участник данных индекса поиска

   • Читатель данных индекса поиска

     Примечание.

     Владелец, участник, читатель и участник службы поиска являются ролями плоскости управления и не предоставляют доступ к данным в индексе поиска. Для доступа к данным выберите роль участника индекса поиска или средства чтения данных индекса поиска. Дополнительные сведения о область и назначении каждой роли см. в статье "Встроенные роли", используемые в поиске.

6. На вкладке "Члены" выберите управляемое удостоверение, которое требуется предоставить службе поиска.

7. Чтобы назначить роль, на вкладке Проверка и назначение выберите Проверка и назначение.

Можно назначить несколько ролей, таких как участник службы поиска и участник данных индекса поиска, если приложению требуется полный доступ к службам поиска, объектам и содержимому.

Вы также можете назначать роли с помощью PowerShell.

Настройка проверки подлинности Microsoft Entra в клиенте

Получив управляемое удостоверение и назначение ролей в службе поиска, вы можете добавить код в приложение для проверки подлинности субъекта безопасности и получения маркера OAuth 2.0.

Используйте следующие клиентские библиотеки для управления доступом на основе ролей:

• azure.search.documents (Azure SDK для .NET)
• azure-search-documents (Azure SDK для Java)
• azure/search-documents (Пакет SDK Azure для JavaScript)
• azure.search.documents (Пакет SDK Azure для Python)

Примечание.

Дополнительные сведения о потоке предоставления кода OAuth 2.0, используемом идентификатором Microsoft Entra ID, см. в статье "Авторизация доступа к веб-приложениям Microsoft Entra" с помощью потока предоставления кода OAuth 2.0.

Пакет SDK для .NET

Приведенные ниже инструкции ссылались на существующий пример C#, чтобы продемонстрировать изменения кода.

1. В качестве отправной точки клонируйте исходный код для раздела C# краткого руководства. Полнотекстовый поиск с помощью пакетов SDK Azure.

   В настоящее время в примере используется проверка подлинности на основе ключей и создание SearchClientSearchIndexClient, AzureKeyCredential но можно внести небольшое изменение, чтобы переключиться на проверку подлинности на основе ролей.

2. Обновите пакет NuGet Azure.Search.Documents до версии 11.4 или более поздней.

3. Импортируйте библиотеку Azure.Identity , чтобы получить доступ к другим методам проверки подлинности.

4. Вместо использования AzureKeyCredential в начале Main()Program.cs используйте 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());
   

Локальное тестирование

Управляемые удостоверения, назначаемые пользователем, работают только в средах Azure. При локальном DefaultAzureCredential запуске этого кода вернитесь к проверке подлинности с помощью учетных данных. Убедитесь, что вы предоставляете себе необходимый доступ к службе поиска, если вы планируете запустить код локально.

1. Убедитесь, что у вашей учетной записи есть назначения ролей для выполнения всех операций в примере краткого руководства. Чтобы создать и запросить индекс, используйте "Средство чтения данных индекса поиска" и "Участник данных индекса поиска".

2. Перейдите к параметрам проверки>>подлинности службы Azure, чтобы выбрать учетную запись входа Azure.

Теперь вы сможете запустить проект из Visual Studio в локальной системе, используя управление доступом на основе ролей для авторизации.

Примечание.

Документация по Azure.Identity содержит дополнительные сведения о DefaultAzureCredential проверке подлинности Microsoft Entra с помощью пакета SDK Azure для .NET. DefaultAzureCredential Предназначен для упрощения работы с пакетом SDK, обрабатывая распространенные сценарии с разумным поведением по умолчанию. Разработчики, которым требуется больше управления или сценарий которых не обслуживается параметрами по умолчанию, должны использовать другие типы учетных данных.

REST API

Использование пакета SDK Для Azure упрощает поток OAuth 2.0, но вы также можете программируйте непосредственно в отношении протокола в приложении. Полные сведения доступны в платформа удостоверений Майкрософт и потоке учетных данных клиента OAuth 2.0.

1. Начните с получения маркера из платформа удостоверений Майкрософт:

   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
   

   Обязательный область — "https://search.azure.com/.default".

2. Теперь, когда у вас есть маркер, вы готовы отправить запрос службе поиска.

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

См. также

• Использование управления доступом на основе ролей Azure в службе "Поиск ИИ Azure"
• Авторизация доступа к веб-приложениям Microsoft Entra с помощью потока предоставления кода OAuth 2.0
• Интеграция с идентификатором Microsoft Entra
• Настраиваемые роли Azure