Aplicação de ACL e RBAC no momento da consulta no Pesquisa de IA do Azure (pré-visualização)

O controlo de acesso no momento da consulta (pré-visualização) garante que os utilizadores só recuperam os resultados de pesquisa a que estão autorizados a aceder, com base na sua identidade, associação a grupos, funções ou atributos. Esta funcionalidade é essencial para pesquisas empresariais seguras e fluxos de trabalho orientados pela conformidade.

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

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

Pré-requisitos

• Os metadados de permissões devem estar em filterable campos de string. Não vais usar o filtro nas tuas consultas, mas o motor de busca constrói um filtro internamente para excluir conteúdos não autorizados.

• Os metadados de permissões devem consistir em permissões ao estilo POSIX que identificam o nível de acesso e o ID do grupo ou utilizador, ou o ID de recurso do contentor na ADLS Gen2 se estiveres a usar o âmbito RBAC.

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

• Dependendo da fonte de dados:

  • Para fontes de dados ADLS Gen2, deve ter listas de controlo de acesso (ACLs) configuradas e/ou funções de controlo de acesso baseado em funções (RBAC) no Azure ao nível do contentor.
  • Para fontes de dados Azure Blob, deve ter atribuições de funções no contentor. Pode usar um indexador incorporado, uma fonte de conhecimento ou APIs Push para indexar metadados de permissão no seu índice.
  • Para fontes de dados SharePoint, deve configurar listas de controlo de acesso (ACLs). Podes usar um indexador SharePoint incorporado e configurá-lo com capacidades de ingestão ACL. Também pode usar uma fonte de conhecimento SharePoint indexada e configurá-la para impor permissões ao nível do documento. As permissões baseadas em grupos, incluindo Grupos do Microsoft 365, são suportadas quando importadas como IDs de objeto do Entra. A expansão do grupo ocorre no momento da consulta através do Microsoft Graph.

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

Limitações

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

• A frescura do LCA depende do método de ingestão. Para evitar decisões de autorização obsoletas, planeie como cada fonte propaga as alterações de permissões ao índice:

  • Um indexador SharePoint agendado atualiza as alterações de permissões ao nível do item em cada execução. As alterações a um âmbito principal (site, biblioteca, lista ou pasta) que são herdadas pelos itens subordinados exigem uma ressincronização.
  • Um indexador ADLS Gen2 requer uma resincronização para atualizar as ACLs.
  • A ingestão personalizada ou push exige que volte a fazer a ingestão dos documentos afetados.

• A visibilidade do documento requer ambos:

  • O papel RBAC da aplicação que chama (cabeçalho de autorização).
  • A identidade do utilizador é transportada por x-ms-query-source-authorization.

• Consultas iniciais baseadas em ACL podem experienciar uma latência mais elevada em comparação com pedidos subsequentes, devido à sobrecarga de cache e resolução de permissões.

• Para conteúdo do SharePoint indexado, um grupo do Microsoft Entra aninhado dentro de um grupo do SharePoint não é expandido. A resolução de grupos transitiva da Microsoft Entra não suporta esta relação mista. Veja Relações de grupo apoiadas.

Limites de entrada ACL por fonte de dados

Os limites de entrada da lista de controlo de acesso (ACL) definem quantos registos de permissões distintos podem ser associados a um ficheiro, pasta ou item dentro de uma fonte de dados conectada. Cada entrada representa uma única identidade de utilizador ou grupo e os direitos de acesso concedidos a essa identidade (por exemplo, Ler, Escrever ou Executar).

O número máximo de entradas ACL suportadas pela funcionalidade do Pesquisa de IA do Azure varia consoante o tipo de fonte de dados:

Azure Data Lake Storage Gen2 (ADLS Gen2): Cada ficheiro ou diretório pode ter até 32 permissões de entradas ACL. Neste contexto, uma entrada significa um único principal (utilizador ou grupo) com um conjunto específico de permissões. Exemplo: atribuir acesso de leitura a «Everyone» e acesso de execução a «Azure users» contaria como duas entradas ACL.

SharePoint no Microsoft 365: A fonte de dados SharePoint na pesquisa suporta até 1.000 entradas de permissões por ficheiro. Cada entrada representa uma atribuição única de utilizador ou grupo na lista de permissões do item. Isto é distinto dos limites globais de permissões únicas por lista ou biblioteca, que determinam quantos itens podem ter permissões únicas.

Estes limites determinam quão granularmente o Pesquisa de IA do Azure pode respeitar as permissões ao nível do item ao indexar ou filtrar resultados de pesquisa. Se um item exceder estes limites de entrada ACL, as permissões para além desse limite podem não ser aplicadas no momento da consulta.

Como funciona a aplicação de políticas em tempo de consulta

Esta secção lista a ordem de operações para a aplicação da ACL no momento da consulta. As operações variam dependendo se utiliza o escopo do Azure RBAC, o grupo do Microsoft Entra ID ou os IDs de utilizador.

1. Entrada de permissões de utilizador

A aplicação do utilizador final inclui um token de acesso de consulta como parte do pedido de pesquisa, e esse token de acesso é geralmente a identidade do utilizador. A tabela seguinte lista a fonte das permissões de utilizador suportadas pelo Pesquisa de IA do Azure para aplicação de ACL:

2. Construção de filtros de segurança

Internamente, o Pesquisa de IA do Azure constrói dinamicamente filtros de segurança com base nas permissões de utilizador fornecidas. Estes filtros de segurança são automaticamente adicionados a quaisquer filtros que possam surgir com a consulta, caso o índice tenha a opção de filtro de permissões ativada.

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

3. Filtragem de resultados

O filtro de segurança faz corresponder de forma eficiente os userIds, groupIds e rbacScope do pedido de pesquisa com cada lista de ACLs em cada documento do índice de pesquisa, limitando os resultados devolvidos àqueles a que o utilizador tem acesso. É importante notar que cada filtro é aplicado de forma independente e um documento é considerado autorizado caso algum filtro tenha sucesso. Por exemplo, se um utilizador tem acesso a um documento através de userIds mas não através de groupIds, o documento continua a ser considerado válido e devolvido ao utilizador.

Grupos SharePoint no momento da consulta

A partir da API REST 2026-05-01-preview, o Pesquisa de IA do Azure pode respeitar a pertença a grupos de sites do SharePoint, como Proprietários, Membros, Visitantes e grupos de sites personalizados, no momento da consulta. Para permitir este cenário, o índice deve incluir:

• Uma propriedade sharePointConnectorAppRegistration que faz referência à credencial de identidade federada da aplicação Microsoft Entra utilizada para chamar o SharePoint em nome do utilizador.
• Um campo marcado com o atributo sharepointSiteUrl: true que armazena o URL do SharePoint site para cada item indexado (normalmente chamado SharePointSiteUrl e preenchido a partir do campo de origem metadata_spo_site_url).

No momento da consulta, o Pesquisa de IA do Azure utiliza a aplicação registada e o URL do site de cada documento candidato para determinar a que grupos do SharePoint pertence o utilizador que efetua o pedido nesse site. Os grupos resolvidos são comparados com os valores com o prefixo spg: armazenados no campo de filtro de permissões groupIds. O prefixo spg: distingue os grupos de sites do SharePoint dos IDs de objeto de grupo do Microsoft Entra, que são armazenados sem um prefixo.

Para detalhes e limitações de configuração, veja Configure SharePoint suporte a grupos.

Se a filtragem de permissões do SharePoint devolver resultados em falta ou inesperados, consulte Resolução de problemas com filtragem de permissões do SharePoint.

Exemplo: Consulta com imposição do grupo do site SharePoint

A solicitação é idêntica à consulta padrão imposta por ACL. O serviço de pesquisa utiliza o sharePointConnectorAppRegistration do índice para determinar a pertença a grupos do SharePoint em nome do chamador. Inclua GroupIds na cláusula select para ver, na resposta, os valores com o prefixo 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"
}

Exemplo de consulta

Aqui está um exemplo de pedido de consulta a partir de código exemplo. O token de consulta é um token de acesso Microsoft Entra para o utilizador que faz a consulta.

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 (pré-visualização)

Depurar consultas que incluam metadados de permissão pode ser problemático porque os resultados de pesquisa são específicos para cada utilizador. Como programador ou administrador, pode precisar de permissões elevadas para devolver resultados independentemente dos metadados de permissões, para poder investigar problemas com consultas que retornam conteúdo não autorizado.

Para investigar, deve ser capaz de:

• Visualize o conjunto de documentos que o utilizador final pode visualizar com base nas permissões desse utilizador.

• Consulte todos os documentos no índice para investigar porque alguns podem não ser visíveis para o utilizador final.

Pode realizar estas tarefas adicionando um cabeçalho personalizado, x-ms-enable-elevated-read: true, a uma consulta.

Permissões para pedidos de leitura elevada

Deve ter permissões de Contribuidor 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 no plano de dados, pelo que o papel personalizado só pode consistir em permissões do plano de dados atómico. 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 configurares as permissões, podes executar a consulta. O exemplo seguinte é um pedido de consulta contra 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
}

Mudança importante no comportamento da funcionalidade ACL em versões específicas da API de pré-visualização

Antes da versão 2025-11-01-preview da API REST, as versões de pré-visualização anteriores, 2025-05-01-preview e 2025-08-01-preview, retornavam todos os documentos ao usar uma chave de API de serviço ou roles autorizados do Entra, mesmo que não fosse fornecido token de utilizador. Aplicações que não validavam a presença de um token de utilizador podiam, inadvertidamente, expor resultados aos utilizadores finais se não forem implementadas corretamente ou não seguirem as melhores práticas.

A partir de novembro de 2025, este comportamento mudou:

• Os filtros de permissões ACL aplicam-se agora mesmo quando se utilizam apenas chaves API de serviço ou autenticação Entra em todas as versões que suportam ACL.
• Se o token de utilizador for omitido, o conteúdo protegido por ACL não é devolvido.
• Para visualizar todos os documentos para fins de resolução de problemas, tem de incluir explicitamente o cabeçalho de leitura elevada ao utilizar a versão 2026-05-01-preview ou posterior da API REST.

Esta atualização ajuda a manter o conteúdo protegido quando as aplicações não aplicam as melhores práticas para validação de tokens.

Conteúdo relacionado

• Tutorial: Indexar metadados de permissão do ADLS Gen2 e consultar com resultados filtrados por permissão (pré-visualização)
• Indexação de listas de controlo de acesso a documentos (ACLs) usando as APIs push REST (pré-visualização)
• Use um indexador ADLS Gen2 para ingerir metadados de permissões e filtrar os resultados da pesquisa com base nos direitos de acesso dos utilizadores (pré-visualização)
• Utilize um indexador blob ou uma fonte de conhecimento para ingestão de metadados dos escopos de RBAC
• Use um indexador SharePoint para ingerir metadados de permissões e filtrar os resultados da pesquisa com base nos direitos de acesso dos utilizadores (pré-visualização)