Aplicação de ACL e RBAC em tempo de consulta no Pesquisa de IA do Azure  (versão prévia)

O controle de acesso em tempo de consulta (versão prévia) garante que os usuários recuperem apenas os resultados da pesquisa que estão autorizados a acessar, com base em sua identidade, associações de grupo, funções ou atributos. Essa funcionalidade é essencial para a pesquisa empresarial segura e fluxos de trabalho controlados por conformidade.

O acesso autorizado depende dos metadados de permissão ingeridos durante a indexação. Para fontes de dados do indexador que têm modelos de acesso embutidos, como Azure Data Lake Storage (ADLS) Gen2 e SharePoint no Microsoft 365, um indexador pode extrair automaticamente os metadados de permissão para cada documento. Para outras fontes de dados, você deve montar o payload do documento por conta própria, e o payload deve incluir tanto o conteúdo quanto os metadados de permissão associados. Em seguida, use as APIs de push para carregar o índice.

Este artigo explica como configurar consultas que usam metadados de permissão para filtrar resultados.

Pré-requisitos

• Os metadados de permissão devem estar em filterable campos de cadeia de caracteres. Você não usará o filtro em suas consultas, mas o mecanismo de pesquisa criará um filtro internamente para excluir conteúdo não autorizado.

• Os metadados de permissão devem consistir em permissões de estilo POSIX que identifiquem o nível de acesso e a ID do grupo ou do usuário, ou a ID do recurso do contêiner no ADLS Gen2 se você estiver usando o escopo RBAC.

• Para aplicação baseada em ACL com ingestão personalizada, armazene userIds e groupIds como IDs de objeto (GUIDs) do Microsoft Entra em campos filtráveis. No momento da consulta, o serviço compara as identidades em x-ms-query-source-authorization com os IDs armazenados. Para obter detalhes do esquema, consulte Indexação de ACLs (listas de controle de acesso de documentos) usando as APIs REST por push (versão prévia).

• Dependendo da fonte de dados:

  • Para fontes de dados do ADLS Gen2, você deve ter configurado as ACLs (listas de controle de acesso) e/ou funções do Azure RBAC (controle de acesso baseado em função) no nível do contêiner.
  • Para as fontes de dados do Azure Blob, você deve ter atribuições de função no contêiner. Você pode usar um indexador interno, uma fonte de conhecimento ou APIs push para indexar metadados de permissão em seu índice.
  • Para SharePoint fontes de dados, você deve configurar ACLs (listas de controle de acesso). Você pode usar um indexador de SharePoint integrado e configurá-lo com capacidades de ingestão de ACL. Você também pode usar uma fonte de conhecimento SharePoint indexada e configurá-la para impor permissões no nível do documento. As permissões baseadas em grupo, incluindo os Grupos do Microsoft 365, são compatíveis quando incluídas como IDs de objeto do Entra. A expansão do grupo ocorre no momento da consulta por meio de Microsoft Graph.

• Use a API REST de prévia mais recente ou um pacote de pré-visualização do SDK do Azure para consultar o índice ou a fonte de conhecimento. Essa versão da API dá suporte a consultas internas que filtram resultados não autorizados.

Limitações

• Se a avaliação de ACL falhar (por exemplo, o API do Graph não estiver disponível), o serviço retornará 5xx e not retornará um conjunto de resultados parcialmente filtrado.

• O nível de atualização das ACLs depende do método de ingestão. Para evitar decisões de autorização obsoletas, planeje como cada origem propaga as alterações de permissão no índice:

  • Um indexador de SharePoint agendado atualiza as alterações de permissão no nível do item em cada execução. As alterações em um escopo pai (site, biblioteca, lista ou pasta) que são herdadas por itens filho exigem uma ressincronização.
  • Um indexador do ADLS Gen2 exige uma ressincronização para atualizar as ACLs.
  • A ingestão personalizada ou por push exige que você reingira os documentos afetados.

• A visibilidade do documento requer ambos:

  • A função RBAC do aplicativo de chamada (cabeçalho de autorização).
  • A identidade do usuário executada por x-ms-query-source-authorization.

• As consultas iniciais baseadas em ACL podem ter maior latência em comparação com as solicitações subsequentes, devido à sobrecarga de resolução de permissões e cache.

• No conteúdo do SharePoint indexado, um grupo do Microsoft Entra aninhado em um grupo do SharePoint não é expandido. A resolução transitiva de grupos no Microsoft Entra não oferece suporte a essa relação mista. Consulte relações de grupo com suporte.

Limites de entradas de ACL por fonte de dados

Os limites de entrada da ACL (lista de controle de acesso) definem quantos registros de permissão distintos podem ser associados a um arquivo, pasta ou item dentro de uma fonte de dados conectada. Cada entrada representa uma única identidade de usuário ou grupo e os direitos de acesso concedidos a essa identidade (por exemplo, Leitura, Gravação ou Execução).

O número máximo de entradas ACL suportadas pela funcionalidade do Pesquisa de IA do Azure  depende do tipo de fonte de dados.

Azure Data Lake Storage Gen2 (ADLS Gen2): Cada arquivo ou diretório pode ter até 32 permissões de entradas ACL. Nesse contexto, uma entrada significa uma única entidade (usuário ou grupo) com um conjunto de permissões específico. Exemplo: atribuir acesso de leitura a "todos" e acesso de execução a "usuários do Azure" contaria como duas entradas ACL.

SharePoint no Microsoft 365: a fonte de dados do SharePoint na pesquisa dá suporte a até 1.000 entradas de permissão por arquivo. Cada entrada representa uma atribuição de usuário ou grupo exclusiva na lista de permissões do item. Isso é diferente dos limites gerais de escopos de permissão exclusivos por lista ou biblioteca, que regem quantos itens podem ter permissões exclusivas.

Esses limites determinam quão granularmente Pesquisa de IA do Azure  podem honrar permissões no nível do item ao indexar ou filtrar os resultados da pesquisa. Se um item exceder esses limites de entradas de ACL, as permissões além do limite talvez não sejam aplicadas durante a consulta.

Como funciona a imposição de tempo de consulta

Esta seção lista a ordem das operações para a aplicação de ACL no momento da consulta. As operações variam dependendo se você usa o escopo do RBAC do Azure ou grupo do Microsoft Entra ID ou IDs de usuário.

1. Entrada de permissões do usuário

O aplicativo do usuário final inclui um token de acesso à consulta como parte da solicitação de consulta de pesquisa e esse token de acesso normalmente é a identidade do usuário. A tabela a seguir lista a origem das permissões de usuário compatíveis com Pesquisa de IA do Azure  para a imposição de ACL:

2. Construção do filtro de segurança

Internamente, Pesquisa de IA do Azure  constrói dinamicamente filtros de segurança com base nas permissões de usuário fornecidas. Esses filtros de segurança são automaticamente adicionados a qualquer filtro que possa ser incluído na consulta, caso o índice tenha a opção de filtro de permissões ativada.

Para Azure RBAC, as permissões são listas de cadeias de caracteres de ID do recurso. Deve haver uma atribuição de função do Azure (Leitor de Dados de Blob de Armazenamento) na fonte de dados que conceda acesso ao token de entidade de segurança no cabeçalho de autorização. O filtro exclui documentos se não houver atribuição de função para o principal por trás do token de acesso na solicitação.

3. Filtragem de resultados

O filtro de segurança corresponde com eficiência a userIds, groupIds e rbacScope direto da solicitação em relação às listas de ACLs em todos os documentos do índice de pesquisa a fim de limitar os resultados a serem retornados apenas aos que o usuário tem acesso. É importante observar que cada filtro é aplicado independentemente e um documento é considerado autorizado se algum filtro for bem-sucedido. Por exemplo, se um usuário tiver acesso a um documento por meio de userIds, mas não por meio de groupIds, o documento ainda será considerado válido e retornado ao usuário.

SharePoint grupos no momento da consulta

A partir da API REST 2026-05-01-preview, a Pesquisa de IA do Azure pode respeitar as associações a grupos de sites do SharePoint, como Proprietários, Membros, Visitantes e grupos personalizados do site, no momento da execução da consulta. Para habilitar esse cenário, o índice deve incluir:

• Uma propriedade sharePointConnectorAppRegistration que faz referência à credencial de identidade federada do aplicativo Microsoft Entra usado para chamar SharePoint em nome do usuário.
• Um campo marcado com o atributo sharepointSiteUrl: true que armazena a URL do site SharePoint para cada item indexado (normalmente denominado SharePointSiteUrl e preenchido do campo de origem metadata_spo_site_url).

No momento da execução da consulta, o Pesquisa de IA do Azure  usa o aplicativo registrado e a URL do site em cada documento candidato para determinar as associações a grupos do SharePoint do usuário que faz a chamada nesse site. Os grupos resolvidos são comparados com os valores prefixados com spg: armazenados no campo de filtro de permissão groupIds. O prefixo spg: distingue grupos de sites do SharePoint de IDs de objeto de grupo do Microsoft Entra, que são armazenados sem prefixo.

Para obter detalhes de configuração e limitações, consulte Configurar o suporte a grupos do SharePoint.

Se a filtragem de permissões do SharePoint retornar resultados ausentes ou inesperados, consulte Solucionar problemas da filtragem de permissões do SharePoint.

Exemplo: Consulta com aplicação de grupo de sites do SharePoint

A solicitação é idêntica à consulta imposta pela ACL padrão. O serviço de pesquisa usa o sharePointConnectorAppRegistration do índice para determinar a associação do chamador aos grupos do SharePoint em nome dele. Inclua GroupIds na cláusula select para ver valores com o prefixo spg: na resposta.

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"
}

Exemplo de consulta

Aqui está um exemplo de uma solicitação de consulta do sample code. O token de consulta é um token de acesso Microsoft Entra para o usuário que está consultando.

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"
}

Permissões elevadas para investigar resultados incorretos (versão prévia)

A depuração de consultas que incluem metadados de permissão pode ser problemática porque os resultados da pesquisa são específicos para cada usuário. Como desenvolvedor ou administrador, talvez seja necessário ter permissões elevadas para retornar resultados independentemente dos metadados de permissão para que você possa investigar problemas com consultas que retornam conteúdo não autorizado.

Para investigar, você deve ser capaz de:

• Exiba o conjunto de documentos que o usuário final pode exibir com base nas permissões desse usuário.

• Exiba todos os documentos no índice para investigar por que alguns podem não estar visíveis para o usuário final.

Você pode realizar essas tarefas adicionando um cabeçalho x-ms-enable-elevated-read: truepersonalizado a uma consulta.

Permissões para solicitações de leitura elevada

Você deve ter permissões de Colaborador de Dados de Índice de Pesquisa ou uma função personalizada que inclua a permissão de Leitura Elevada.

As consultas são uma operação de plano de dados, portanto, a função personalizada só pode consistir em permissões de plano de dados atômicos. Para uma função personalizada, adicione a permissão Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read.

Adicionar um cabeçalho de leitura elevada a uma consulta

Depois de configurar as permissões, você pode executar a consulta. O exemplo a seguir é uma solicitação de consulta em um índice de pesquisa.

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
}

Alteração importante do comportamento da funcionalidade ACL em versões de API específicas de visualização

Antes da versão 2025-11-01-preview da API REST, versões anteriores 2025-05-01-preview e 2025-08-01-preview retornavam todos os documentos ao usar uma chave de API de serviço ou funções de Entra autorizadas, mesmo quando nenhum token de usuário era fornecido. Aplicativos que não validaram a presença de um token de usuário podem expor inadvertidamente os resultados aos usuários finais se não forem implementados corretamente ou seguindo as práticas recomendadas.

A partir de novembro de 2025, esse comportamento mudou:

• Os filtros de permissão ACL agora se aplicam mesmo quando se utiliza apenas chaves de API de serviço ou autenticação do Entra em todas as versões que dão suporte à ACL.
• Se o token de usuário for omitido, o conteúdo protegido por ACL não será retornado.
• Para exibir todos os documentos para solução de problemas, você deve incluir explicitamente o cabeçalho de leitura elevada ao usar a versão 2026-05-01-preview da API REST ou posterior.

Essa atualização ajuda a manter o conteúdo protegido quando os aplicativos não impõem práticas recomendadas para validação de token.

Conteúdo relacionado

• Tutorial: Indexar metadados de permissão do ADLS Gen2 e consultar resultados filtrados por permissão (versão prévia)
• Indexação de listas de controle de acesso (ACLs) de documentos usando as APIs REST de envio por push (versão prévia)
• Usar um indexador do ADLS Gen2 para ingerir metadados de permissão e filtrar os resultados da pesquisa com base nos direitos de acesso do usuário (versão prévia)
• Use um indexador de blobs ou uma fonte de conhecimento para importar metadados de escopos RBAC
• Use um indexador SharePoint para ingerir metadados de permissão e filtrar os resultados da pesquisa com base nos direitos de acesso do usuário (versão prévia)