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

Статья
01/16/2025

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

Внимание

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

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

Примечание.

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

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

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

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

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

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

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

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

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

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

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

Иногда для принятия в силу назначений ролей может потребоваться пять–десять минут. До этого следующее сообщение отображается на страницах портал 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:

Войдите в портал 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 в запросе автоматически (если они указаны).

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

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

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