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

Note

Поиск с использованием ИИ Azure доступна через портал Azure, REST API и Azure SDKs. Он также лежит в основе Foundry IQ — управляемого слоя знаний, который преобразует корпоративный контент в многократно используемые базы знаний с учетом разрешений доступа для агентов на портале Microsoft Foundry.

В этой статье объясняется, как включить управление доступом на основе ролей (RBAC) для операций с данными в службе Azure Cognitive Search. С включенной функцией RBAC можно использовать проверку подлинности идентификатора Microsoft Entra вместо ключей API.

Внимание

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

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

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

Предварительные требования

Служба поиска в любом регионе на любом уровне, включая бесплатную.
Владелец, Администратор доступа пользователей или пользовательская роль с разрешениями Microsoft.Authorization/roleAssignments/write для включения RBAC.
После включения RBAC требуются роли для плоскости данных для доступа к содержимому: Участник службы поиска, Участник данных индекса поиска и Читатель данных индекса поиска. Дополнительные сведения см. в разделе "Назначение ролей ".

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

Настройте службу поиска для распознавания заголовка авторизации в запросах данных, которые предоставляют маркер доступа 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

Ссылка:обновление службы поиска az

Дополнительные сведения см. в статье «Управление службой 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

Справочник:Set-AzSearchService

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

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

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

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

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2025-05-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=2025-05-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```
Успешный запрос возвращает 200 OK с обновленной конфигурацией службы.

Reference:Services — создание или обновление

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

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

Чтобы отключить управление доступом на основе ролей в портал 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=2025-05-01

Используйте PATCH для обновления конфигурации службы. В следующем изменении для параметра authOptions задано значение NULL.
```
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-05-01
{
    "properties": {
        "disableLocalAuth": true
    }
}
```
Успешный запрос возвращает 200 OK с обновленной конфигурацией службы.

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

Reference:Services — создание или обновление

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

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-03-27