Бөлісу құралы:

Подключение к поиску ИИ Azure с помощью ролей

  • Мақала

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

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

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

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

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

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

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

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

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

Объедините эти роли, чтобы получить достаточные разрешения для вашего варианта использования.

Примечание.

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

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

В этом разделе назначьте роли для:

Назначение ролей для администрирования службы

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

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

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

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

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

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

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

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

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

Назначение ролей для разработки

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

Другое сочетание ролей, предоставляющих полный доступ, — участник или владелец, а также средство чтения данных индекса поиска.

Внимание

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

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

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

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

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

    Страница

  5. Выберите роль:

    • Участник службы поиска (операции create-read-update-delete для индексов, индексаторов, наборов навыков и других объектов верхнего уровня)
    • Участник данных индекса поиска (загрузка документов и выполнение заданий индексирования)
    • Средство чтения данных индексов поиска (запрос индекса)

    Другое сочетание ролей, предоставляющих полный доступ, — участник или владелец, а также средство чтения данных индекса поиска.

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

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

  8. Повторите для других ролей. Большинству разработчиков нужны все три.

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

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

Это очень конкретная роль. Он предоставляет доступ GET или POST к коллекции документов индекса поиска для поиска, автозаполнения и предложений. Он не поддерживает операции GET или LIST в индексе или других объектах верхнего уровня или статистике службы GET.

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

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

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

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

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

  5. Выберите роль читателя индексов поиска.

  6. На вкладке "Участники" выберите удостоверение пользователя Или группы Microsoft Entra. Если вы настраиваете разрешения для другой службы, вы можете использовать системное или управляемое пользователем удостоверение. Выберите этот параметр, если назначение роли предназначено для удостоверения службы.

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

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

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

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

  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. Выберите "Проверить и создать" , чтобы создать роль. Теперь вы можете назначить пользователей и группы роли.

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

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

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

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

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

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

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

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

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

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

Внимание

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

Ограничения

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

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

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

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

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

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