Принудительное применение ACL и RBAC во время запроса в Поиск с использованием ИИ Azure

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

Авторизованный доступ зависит от метаданных разрешений, которые получаются во время индексирования. Для источников данных индексатора, имеющих встроенные модели доступа, такие как Azure Data Lake Storage (ADLS) 2-го поколения и SharePoint в Microsoft 365, индексатор может автоматически извлекать метаданные разрешений для каждого документа. Для других источников данных необходимо самостоятельно собрать пакет данных документа, а пакет данных должен включать и содержимое, и данные о разрешениях. Затем вы используете API push-уведомлений для загрузки индекса.

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

Предпосылки

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

• Метаданные разрешений должны состоять из разрешений в стиле POSIX, определяющих уровень доступа и группу или идентификатор пользователя, или идентификатор ресурса контейнера в ADLS 2-го поколения, если вы используете область RBAC.

• В зависимости от источника данных:

  • Для источников данных ADLS 2-го поколения необходимо настроить списки управления доступом (ACL) и/или роли на основе доступа Azure (RBAC) на уровне контейнера.
  • Для источников данных Azure Blob вы должны иметь назначенные роли в контейнере данных. Вы можете использовать встроенный индексатор, источник знаний или push-интерфейсы API для индексирования метаданных разрешений в индексе.
  • Для источников данных SharePoint необходимо настроить списки управления доступом (ACL). Вы можете использовать встроенный индексатор SharePoint и настроить его с помощью возможностей приема ACL.

• Используйте последнюю предварительную версию REST API или пакет предварительной версии Azure SDK, чтобы запросить индекс или источник знаний. Эта версия API поддерживает внутренние запросы, которые фильтруют несанкционированные результаты.

Limitations

• Если оценка ACL завершается ошибкой (например, API Graph недоступна), служба возвращает 5xx и не будет возвращать частично отфильтрованный результат.

• Для видимости документов требуется оба:

  • роль RBAC вызывающего приложения (заголовок авторизации)
  • удостоверение пользователя, несущееся через x-ms-query-source-authorization

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

Ограничения записи ACL для каждого источника данных

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

Максимальное количество записей ACL, поддерживаемых функциональностью Поиск с использованием ИИ Azure, зависит от типа источника данных:

Azure Data Lake Storage 2-го поколения (ADLS 2-го поколения): каждый файл или каталог может иметь до 32 записей доступа ACL. В этом контексте запись означает один субъект (пользователь или группа) с определенным набором разрешений. Пример: назначение доступа на чтение для "Все" и доступа на выполнение для "пользователи Azure" считалось бы двумя записями ACL.

SharePoint в Microsoft 365: Источник данных SharePoint в поисковой системе поддерживает до 1000 разрешений на один файл. Каждая запись представляет уникальное назначение пользователя или группы в списке разрешений элемента. Это отличается от общих ограничений уникальных областей разрешений для каждого списка или библиотеки, которое определяет, сколько элементов может иметь уникальные разрешения.

Эти ограничения определяют, как детально Поиск с использованием ИИ Azure могут учитывать разрешения на уровне элементов при индексировании или фильтрации результатов поиска. Если элемент превышает эти ограничения записи ACL, разрешения, превышающие ограничение, могут не применяться во время запроса.

Принцип работы контроля выполнения запросов

В этом разделе перечислены порядок операций для внедрения ACL при выполнении запроса. Операции зависят от того, используете ли вы область RBAC Azure или идентификаторы пользователей или групп Microsoft Entra ID.

1. Входные данные разрешений пользователя

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

2. Построение фильтра безопасности

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

Для Azure RBAC разрешения — это списки строк идентификатора ресурса. В источнике данных должна быть назначена роль Azure (Storage Blob Data Reader), которая предоставляет доступ к токену субъекта безопасности в заголовке авторизации. Фильтр исключает документы, если в запросе нет назначения ролей для субъекта за маркером доступа.

3. Фильтрация результатов

Фильтр безопасности эффективно сопоставляет идентификаторы пользователей, групповые идентификаторы и rbacScope из запроса со списком ACL в каждом документе индекса поиска, чтобы ограничить результаты только теми, к которым у пользователя есть доступ. Важно отметить, что каждый фильтр применяется независимо, и документ считается авторизованным, если любой фильтр успешно выполнен. Например, если у пользователя есть доступ к документу через userIds, но не через groupIds, документ по-прежнему считается допустимым и возвращается пользователю.

Пример запроса

Ниже приведен пример запроса из кода ample code. Маркер запроса передается в заголовке запроса. Токен запроса — это личный токен доступа пользователя или групповой учетной записи, стоящей за запросом.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2025-11-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

Повышенные разрешения для исследования неправильных результатов

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

Для изучения необходимо иметь возможность:

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

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

Эти задачи можно выполнить, добавив в запрос пользовательский заголовок x-ms-enable-elevated-read: true.

Разрешения для запросов с расширенными привилегиями для чтения

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

Запросы — это операция плоскости данных, поэтому пользовательская роль может состоять только из разрешений атомарного уровня данных. Добавьте разрешение Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read для настраиваемой роли.

Добавление заголовка с высоким уровнем доступа для чтения в запрос

После настройки разрешений можно запустить запрос. Следующий пример — запрос к индексу поиска.

POST {endpoint}/indexes('{indexName}')/search.post.search?api-version=2025-11-01-preview
Authorization: Bearer {AUTH_TOKEN}
x-ms-query-source-authorization: {TOKEN}
x-ms-enable-elevated-read: true

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

Важное изменение поведения функциональности ACL в специфических предварительных версиях API

До версии 2025-11-01-preview REST API более ранние предварительные версии 2025-05-01-preview и 2025-08-01-preview возвращали все документы с использованием служебного ключа API или авторизованных ролей Entra, даже если токен пользователя не был предоставлен. Приложения, которые не проверяют наличие маркера пользователя, могут непреднамеренно предоставлять результаты конечным пользователям, если их реализация выполнена неправильно или без соблюдения лучших практик.

Начиная с ноября 2025 года это поведение изменилось:

• Фильтры разрешений ACL теперь применяются даже при использовании только ключей API службы или проверки подлинности Entra во всех версиях, поддерживающих ACL.
• Если маркер пользователя опущен, содержимое, защищенное ACL, не возвращается.
• Чтобы просмотреть все документы для устранения неполадок, необходимо явно включить заголовок с повышенными привилегиями при использовании версии REST API 2025-11-01-preview.

Это обновление помогает защитить содержимое, если приложения не применяют рекомендации по проверке маркеров.

См. также

• Руководство по индексу метаданных разрешений ADLS 2-го поколения

• Индексирование ACL и RBAC с использованием push API в Поиск с использованием ИИ Azure

• Использование индексатора ADLS 2-го поколения для приема метаданных разрешений и фильтрации результатов поиска на основе прав доступа пользователей

• Использование индексатора Blob для извлечения метаданных областей RBAC

• Использовать индексатор SharePoint для приема метаданных разрешений и фильтрации результатов поиска на основе прав доступа пользователей