Включение или отключение управления доступом на основе ролей в службе "Поиск ИИ Azure"

Статья
10/30/2024

Поиск azure AI использует проверку подлинности на основе ключей по умолчанию, но полностью поддерживает проверку подлинности и авторизацию идентификатора Microsoft Entra для всех операций уровня управления и плоскости данных с помощью управления доступом на основе ролей Azure (RBAC).

Прежде чем назначать роли для авторизованного доступа к службе поиска ИИ Azure, необходимо включить управление доступом на основе ролей в службе поиска. Роли администрирования служб (плоскости управления) встроены и не могут быть включены или отключены.

Примечание.

Плоскость данных относится к операциям с конечной точкой службы поиска, например индексированием или запросами, или любой другой операцией, указанной в REST API службы поиска или эквивалентными клиентскими библиотеками azure SDK. Плоскость управления относится к управлению ресурсами Azure, например созданию или настройке службы поиска.

Необходимые компоненты

Служба поиска в любом регионе на любом уровне, включая бесплатную.
Владелец, администратор доступа пользователей или пользовательская роль с разрешениями Microsoft.Authorization/roleAssignments/write .

Включение доступа на основе ролей для операций плоскости данных

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

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

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

Войдите в портал Azure и откройте страницу службы поиска.
Выберите "Параметры" и выберите "Ключи" в области навигации слева.

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

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

Если вы выбираете подход только для ролей, назначьте роли плоскости данных учетной записи пользователя для восстановления полного административного доступа через операции плоскости данных в портал Azure. К ролям относятся участник службы поиска, участник данных индекса поиска и средство чтения данных индексов поиска. Вам нужны все три роли, если требуется эквивалентный доступ.

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

Выполните этот скрипт, чтобы поддерживать только роли:

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

Или запустите этот скрипт для поддержки ключей и ролей:

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

Дополнительные сведения см. в статье "Управление azure AI служба с помощью Azure CLI".

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

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

Кроме того, выполните следующую команду для поддержки ключей и ролей:

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

Дополнительные сведения см. в статье "Управление служба ИИ Azure с помощью PowerShell".

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

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

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

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

Используйте 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"
            }
        }
    }
}
```

Отключение управления доступом на основе ролей

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

Отмените описанные ранее действия, чтобы включить доступ на основе ролей.

Войдите в портал Azure и откройте страницу службы поиска.
Выберите "Параметры" и выберите "Ключи" в области навигации слева.
Выберите Ключи API.

Отключение проверки подлинности на основании ключа API

Доступ к ключу или локальная проверка подлинности может быть отключена в службе, если вы используете исключительно встроенные роли и проверку подлинности Microsoft Entra. Отключение ключей API приводит к отказу службы поиска всех запросов, связанных с данными, которые передают ключ API в заголовке.

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

Разрешения владельца или участника необходимы для отключения функций безопасности.

В портал Azure перейдите в службу поиска.
В области навигации слева выберите "Ключи".
Выберите управление доступом на основе ролей.

Изменение действует немедленно, но подождите несколько секунд до тестирования. Если у вас есть разрешение на назначение ролей в качестве члена владельца, администратора службы или соадминистратора, вы можете использовать функции портала для тестирования доступа на основе ролей.

Чтобы отключить проверку подлинности на основе ключей, установите для параметра -disableLocalAuth значение true. Это тот же синтаксис, что и сценарий включения только ролей, представленный в предыдущем разделе.

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

Чтобы повторно включить проверку подлинности ключа, установите для параметра -disableLocalAuth значение false. Служба поиска возобновляет прием ключей API в запросе автоматически (если они указаны).

Дополнительные сведения см. в статье "Управление azure AI служба с помощью Azure CLI".

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

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

Чтобы повторно включить проверку подлинности ключа, установите для параметра DisableLocalAuth значение false. Служба поиска возобновляет прием ключей API в запросе автоматически (если они указаны).

Дополнительные сведения см. в статье "Управление служба ИИ Azure с помощью PowerShell".

Чтобы отключить проверку подлинности на основе ключей, установите для параметра disableLocalAuth значение true.

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

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

Используйте PATCH для обновления конфигурации службы. В следующем изменении для параметра authOptions задано значение 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
    }
}

Чтобы повторно включить проверку подлинности ключа, установите для параметра disableLocalAuth значение false. Служба поиска возобновляет прием ключей API в запросе автоматически (если они указаны).

Эффекты управления доступом на основе ролей

Управление доступом на основе ролей может увеличить задержку некоторых запросов. Каждое уникальное сочетание ресурсов службы (индексатор, индексатор, наборы навыков и т. д.) и субъект-служба активирует проверку авторизации. Эти проверки авторизации могут содержать до 200 миллисекунда задержки на запрос.
В редких случаях, когда запросы исходят из большого количества разных субъектов-служб, все целевые ресурсы службы (индексы, индексаторы и т. д.) могут привести к регулированию. Регулирование произойдет только в том случае, если в секунду использовались сотни уникальных сочетаний ресурсов службы поиска и субъекта-службы.

Следующие шаги

Настройка ролей для доступа к службе поиска

Поделиться через