Подключение в поиск azure AI с помощью управления доступом на основе ролей

Azure предоставляет глобальную систему авторизации на основе ролей для всех служб, работающих на платформе. В службе "Поиск по искусственному интеллекту Azure" можно использовать роли Azure для:

  • Операции плоскости управления (задачи администрирования службы с помощью Azure Resource Manager).

  • Операции плоскости данных, такие как создание, загрузка и запрос индексов.

Доступ на пользователя через результаты поиска (иногда называется безопасностью на уровне строк или безопасностью на уровне документов) не поддерживается. В качестве обходного решения создайте фильтры безопасности, которые обрезают результаты по удостоверению пользователя, удаляя документы, для которых запрашивающий не должен иметь доступа.

Примечание.

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

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

Роль Плоскость Description
Ответственное лицо Управление и данные Полный доступ к плоскости управления ресурса поиска, включая возможность назначения ролей Azure. Только роль владельца может включать или отключать параметры проверки подлинности или управлять ролями для других пользователей. По умолчанию администраторы подписок являются участниками.

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

На плоскости данных эта роль имеет тот же доступ, что и роль участника службы поиска. Он включает доступ ко всем действиям плоскости данных, кроме возможности запрашивать или индексировать документы.
Читатель Управление и данные Доступ на чтение во всей службе, включая метрики поиска, метрики содержимого (используемое хранилище, количество объектов), а также определения объектов ресурсов плоскости данных (индексы, индексаторы и т. д.). Однако он не может считывать ключи API или читать содержимое в индексах.
Участник службы поиска Управление и данные Доступ на чтение и запись к определениям объектов (индексы, псевдонимы, карты синонимов, индексаторы, источники данных и наборы навыков). Эта роль предназначена для разработчиков, создающих объекты, а также для администраторов, которые управляют службой поиска и его объектами, но без доступа к содержимому индекса. Эта роль позволяет создавать, удалять и перечислять индексы, получать определения индексов, получать сведения о службе (статистика и квоты), тест-анализаторы, создавать карты синонимов, индексаторы, источники данных и наборы навыков. См Microsoft.Search/searchServices/* . список разрешений.
Участник данных индекса поиска Data Доступ на чтение и запись к содержимому в индексах. Эта роль предназначена для разработчиков или владельцев индексов, которые должны импортировать, обновить или запросить коллекцию документов индекса. Эта роль не поддерживает создание или управление индексами. По умолчанию эта роль используется для всех индексов в службе поиска. Чтобы сузить область, см. раздел "Предоставить доступ к одному индексу".
Читатель данных индекса поиска Data Доступ только для чтения для запросов индексов поиска. Эта роль предназначена для приложений и пользователей, выполняющих запросы. Эта роль не поддерживает доступ на чтение к определениям объектов. Например, невозможно прочитать определение индекса поиска или получить статистику службы поиска. По умолчанию эта роль используется для всех индексов в службе поиска. Чтобы сузить область, см. раздел "Предоставить доступ к одному индексу".

Примечание.

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

Ограничения

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

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

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

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

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

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

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

    Снимок экрана: страница

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

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

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

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

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

Назначение ролей

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

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

Назначения ролей на портале являются службами. Если вы хотите предоставить разрешения одному индексу, используйте PowerShell или Azure CLI.

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

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

  3. На расположенной слева панели навигации щелкните Управление доступом (IAM).

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

    Страница

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

    • Владелец
    • Участник
    • Читатель
    • Участник службы поиска
    • Участник данных индекса поиска
    • Читатель данных индекса поиска
  6. На вкладке "Участники" выберите удостоверение пользователя Или группы Microsoft Entra.

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

Тестирование назначений ролей

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

Убедитесь, что вы регистрируете клиентское приложение с идентификатором Microsoft Entra ID и имеете назначения ролей перед тестированием доступа.

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

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

  3. На странице "Обзор" перейдите на вкладку Индексы.

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

    • Участники индекса поиска могут загружать и запрашивать документы. Чтобы проверить разрешения, используйте обозреватель поиска для запроса документов. На портале за пределами мастера импорта данных нет параметра загрузки документов. Так как мастер также создает объекты, вам потребуется участник службы поиска, а также участник данных индекса поиска.

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

Тестирование от имени текущего пользователя

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

  1. Получите маркер носителя для текущего пользователя с помощью Azure CLI:

    az account get-access-token --scope https://search.azure.com/.default
    

    Или с помощью PowerShell:

    Get-AzAccessToken -ResourceUrl https://search.azure.com
    
  2. В новый текстовый файл в Visual Studio Code вставьте следующие переменные:

    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
    @index-name = PASTE-YOUR-INDEX-NAME-HERE
    @token = PASTE-YOUR-TOKEN-HERE
    
  3. Вставьте и отправьте запрос для подтверждения доступа. Вот тот, который запрашивает индекс hotels-quickstart

    POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
      Content-type: application/json
      Authorization: Bearer {{token}}
    
        {
             "queryType": "simple",
             "search": "motel",
             "filter": "",
             "select": "HotelName,Description,Category,Tags",
             "count": true
         }
    

Предоставление доступа к одному индексу

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

Портал в настоящее время не поддерживает назначения ролей на этом уровне детализации, но его можно сделать с помощью PowerShell или Azure CLI.

В PowerShell используйте New-AzRoleAssignment, указав имя пользователя или группы Azure и область назначения.

  1. Azure Загрузите и модули и AzureAD подключитесь к учетной записи Azure:

    Import-Module -Name Az
    Import-Module -Name AzureAD
    Connect-AzAccount
    
  2. Добавьте назначение ролей, область в отдельный индекс:

    New-AzRoleAssignment -ObjectId <objectId> `
        -RoleDefinitionName "Search Index Data Contributor" `
        -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
    

Создание пользовательской роли

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

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

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

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

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

  2. В области навигации слева выберите контроль доступа (IAM).

  3. На панели действий выберите "Роли".

  4. Щелкните правой кнопкой мыши средство чтения данных индекса поиска (или другую роль) и выберите "Клонировать ", чтобы открыть мастер создания настраиваемой роли .

  5. На вкладке "Основные сведения" укажите имя настраиваемой роли, например "Поиск данных индекса Обозреватель", а затем нажмите кнопку "Далее".

  6. На вкладке "Разрешения" нажмите кнопку "Добавить разрешение".

  7. На вкладке "Добавление разрешений" найдите и выберите плитку Поиск (Майкрософт).

  8. Задайте разрешения для пользовательской роли. В верхней части страницы с помощью выбора действий по умолчанию:

    • В разделе Microsoft.Search/operations выберите "Чтение: вывод списка всех доступных операций".
    • В разделе Microsoft.Search/searchServices/indexes выберите "Чтение: чтение индекса".
  9. На той же странице переключитесь на действия данных и в разделе Microsoft.Search/searchServices/indexes/documents выберите "Чтение: чтение документов".

    Определение JSON выглядит следующим образом:

    {
     "properties": {
         "roleName": "search index data explorer",
         "description": "",
         "assignableScopes": [
             "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
         ],
         "permissions": [
             {
                 "actions": [
                     "Microsoft.Search/operations/read",
                     "Microsoft.Search/searchServices/indexes/read"
                 ],
                 "notActions": [],
                 "dataActions": [
                     "Microsoft.Search/searchServices/indexes/documents/read"
                 ],
                 "notDataActions": []
             }
         ]
       }
     }
    
  10. Выберите "Проверить и создать" , чтобы создать роль. Теперь вы можете назначить пользователей и группы роли.

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

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

Примечание.

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

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

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

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

  2. В области навигации слева выберите "Ключи".

  3. Выберите управление доступом на основе ролей.

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

Условный доступ

Рекомендуется использовать условный доступ Microsoft Entra, если необходимо применить политики организации, такие как многофакторная проверка подлинности.

Чтобы включить политику условного доступа для поиска ИИ Azure, выполните следующие действия.

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

  2. Найдите условный доступ Microsoft Entra.

  3. Выберите Политики.

  4. Выберите Новая политика.

  5. В разделе "Облачные приложения" или "Действия " политики добавьте поиск ИИ Azure в качестве облачного приложения в зависимости от способа настройки политики.

  6. Обновите оставшиеся параметры политики. Например, укажите, к каким пользователям и группам применяется эта политика.

  7. Сохраните политику.

Внимание

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

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

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

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