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

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

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

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

Необходимые условия

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

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

• Для принудительного применения на основе ACL с настраиваемым приемом данных храните userIds и groupIds как идентификаторы объектов Microsoft Entra (GUID) в полях с возможностью фильтрации. При выполнении запроса служба сопоставляет идентификаторы в x-ms-query-source-authorization с сохранёнными идентификаторами. Сведения о схеме см. в разделе Индексирование списков управления доступом (ACL) к документам с помощью REST API отправки (предварительная версия).

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

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

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

Ограничения

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

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

  • Запланированный индексатор SharePoint обновляет изменения разрешений на уровне элементов при каждом запуске. Изменения родительской области (сайта, библиотеки, списка или папки), унаследованные дочерними элементами, требуют повторной синхронизации.
  • Индексатор ADLS 2-го поколения требует повторной синхронизации для обновления списков управления доступом.
  • Пользовательский или push-прием данных требует повторной загрузки затронутых документов.

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

  • Роль RBAC вызывающего приложения (заголовок авторизации).
  • Идентификатор пользователя, передаваемый в x-ms-query-source-authorization.

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

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

Ограничения записи 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.

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

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

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

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

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

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

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

группы SharePoint во время запроса

Начиная с REST API 2026-05-01-preview, Поиск с использованием ИИ Azure может учитывать членство в группах сайтов SharePoint, таких как владельцы, члены, посетители и пользовательские группы сайтов во время запроса. Чтобы включить этот сценарий, индекс должен включать:

• Свойство sharePointConnectorAppRegistration, которое ссылается на учетные данные федеративного удостоверения приложения Microsoft Entra, используемого для вызова SharePoint от имени пользователя.
• Поле, помеченное атрибутом sharepointSiteUrl: true, которое хранит URL-адрес сайта SharePoint для каждого индексированного элемента (обычно называется SharePointSiteUrl и заполняется из поля источника metadata_spo_site_url).

Во время выполнения запроса Поиск с использованием ИИ Azure использует зарегистрированное приложение и URL-адрес сайта для каждого документа-кандидата, чтобы определить членство пользователя, выполняющего запрос, в группах SharePoint на этом сайте. Определённые группы сопоставляются со значениями с префиксом spg:, которые хранятся в поле фильтра разрешений groupIds. Префикс spg: отличает группы сайтов SharePoint от идентификаторов объектов группы Microsoft Entra, которые хранятся без префикса.

Сведения о конфигурации и ограничениях см. в разделе Поддержка групп SharePoint.

Если фильтрация разрешений SharePoint возвращает отсутствующие или непредвиденные результаты, см. статью "Устранение неполадок SharePoint фильтрации разрешений".

Пример. Запрос с применением SharePoint групп сайта

Запрос идентичен стандартному принудительному запросу ACL. Служба поиска использует sharePointConnectorAppRegistration индекса для определения членства в группах SharePoint от имени вызывающей стороны. Включите GroupIds в условие select, чтобы увидеть значения с префиксом spg: в ответе.

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

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

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

Вот пример запроса из образец кода. Маркер запроса — это маркер доступа Microsoft Entra для запрашивающего пользователя.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-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=2026-08-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, не возвращается.
• Чтобы просмотреть все документы при устранении неполадок, необходимо явно указать заголовок elevated-read при использовании REST API версии 2026-05-01-preview или более поздней.

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

Связанный контент

• Руководство: индексирование метаданных разрешений из ADLS Gen2 и выполнение запросов с результатами, отфильтрованными по разрешениям (предварительная версия)
• Индексирование списков управления доступом к документам (ACL) с помощью push REST API (предварительная версия)
• Использование индексатора ADLS 2-го поколения для приема метаданных разрешений и фильтрации результатов поиска на основе прав доступа пользователей (предварительная версия)
• Используйте индексатор BLOB или источник знаний для получения метаданных областей RBAC
• Использование индексатора SharePoint для приема метаданных разрешений и фильтрации результатов поиска на основе прав доступа пользователей (предварительная версия)