Controlo de acesso ao nível de documento no Pesquisa de IA do Azure

O Pesquisa de IA do Azure suporta controlo de acesso ao nível do documento, permitindo às organizações aplicar permissões detalhadas ao nível do documento, desde a ingestão de dados até à execução de consultas. Esta capacidade é essencial para construir sistemas agentes de IA seguros, integrando dados, aplicações de geração aumentada por recuperação de dados (RAG) e soluções de pesquisa empresarial que requerem verificações de autorização a nível de documento.

Abordagens para controlo de acesso ao nível de documentos

O Pesquisa de IA do Azure fornece quatro abordagens principais para impor permissões ao nível do documento, cada uma adequada a diferentes fontes de dados e modelos de identidade.

Para fontes de conhecimento indexadas, ingestionPermissionOptions não pode ser combinado com assetStore. Portanto, a visualização de imagens (pré-visualização) não está disponível quando a ingestão nativa de permissões ao nível do documento está ativada.

Escolha uma abordagem

Use os seguintes critérios para identificar a abordagem que melhor se adequa à sua fonte de dados, modelo de identidade e requisitos de conformidade.

Padrão para corte de segurança usando filtros

Para cenários em que a integração nativa de âmbitos ACL/RBAC não é viável, use filtros de cadeias de segurança para restringir os resultados com base em critérios de exclusão. O padrão inclui os seguintes componentes:

• Para armazenar identidades de utilizadores ou grupos, crie um campo string no índice.
• Carregue o índice usando um documento fonte que inclua ACLs associadas.
• Inclua uma expressão de filtro na sua lógica de consulta para correspondência na cadeia.
• No momento da consulta, obtenha a identidade do interlocutor.
• Passe a identidade do chamador como a cadeia de caracteres do filtro.
• Os resultados são cortados para excluir quaisquer correspondências que não incluam a cadeia de identidade do utilizador ou do grupo.

Podes usar APIs de modelos push ou pull. Como esta abordagem é independente da API, só precisa de confirmar que o índice e a consulta têm strings (identidades) válidas para a etapa de filtragem.

Esta abordagem é útil para sistemas com modelos de acesso personalizados ou frameworks de segurança que não sejam da Microsoft. Para mais informações sobre esta abordagem, consulte Filtros de segurança para recorte de resultados em Pesquisa de IA do Azure.

Padrão para suporte nativo a permissões de âmbito ACL e RBAC semelhantes a POSIX (pré-visualização)

O suporte nativo baseia-se em utilizadores da Microsoft Entra e grupos afiliados a documentos que pretende indexar e consultar.

Os contentores Azure Data Lake Storage (ADLS) Gen2 suportam ACLs no contentor e nos ficheiros. Para ADLS Gen2, a preservação do âmbito RBAC ao nível do documento é suportada nativamente quando se usa um indexador ADLS Gen2 ou uma fonte de conhecimento Blob (suporta ADLS Gen2) e uma API de pré-visualização para ingerir conteúdo. Para blobs do Azure que utilizam o indexador de blobs do Azure ou uma fonte de conhecimento, a preservação do âmbito do RBAC está ao nível do contentor.

Para conteúdos protegidos por ACL, use o acesso em grupo em vez do acesso individual do utilizador para facilitar a gestão. O padrão inclui os seguintes componentes:

• Comece com documentos ou ficheiros que tenham atribuições ACL.
• Ativa os filtros de permissões no índice.
• Adicione um filtro de permissões a um campo string num índice.
• Carregue o índice com documentos fonte com ACLs associadas.
• Consulta o índice, adicionando x-ms-query-source-authorization no cabeçalho do pedido.

A sua aplicação cliente recebe permissões de leitura para o índice através do Leitor de Dados do Índice de Pesquisa ou do papel de Contribuidor de Dados do Índice de Pesquisa . O acesso no momento da consulta é determinado pelos metadados de permissão do utilizador ou grupo no conteúdo indexado. Consultas que incluem um filtro de permissões passam um token de utilizador ou grupo tal como x-ms-query-source-authorization no cabeçalho do pedido. Quando usa filtros de permissões na altura da consulta, o Pesquisa de IA do Azure verifica duas coisas:

• Primeiro, verifica a permissão do Search Index Data Reader que permite à sua aplicação cliente aceder ao índice.

• Em segundo lugar, considerando o token extra na solicitação, verifica permissões de utilizador ou grupo nos documentos devolvidos nos resultados de pesquisa, excluindo os que não corresponderem.

Para incluir metadados de permissões no índice, utilize a API do modelo push, enviando documentos JSON para o índice de pesquisa, em que a carga útil inclui um campo de cadeia de caracteres que fornece ACLs de tipo POSIX para cada documento. A diferença importante entre esta abordagem e a restrição de segurança é que os metadados do filtro de permissões no índice e na consulta são reconhecidos como autenticação do Microsoft Entra ID, enquanto a estratégia alternativa para a restrição de segurança é uma simples comparação de strings. Além disso, podes usar o Graph SDK para recuperar as identidades.

Também pode usar as APIs do modelo pull (indexador) se a fonte de dados for Azure Data Lake Storage (ADLS) Gen2 e o seu código chamar uma API de pré-visualização para indexação.

Recuperar metadados de permissões ACL durante o processo de ingestão de dados (pré-visualização)

A forma como recuperas permissões ACL varia dependendo se estás a enviar um payload de documentos ou a usar o indexador ADLS Gen2.

Comece com uma API de pré-visualização que forneça a funcionalidade:

• 2026-08-01-preview REST API
• Pacote de pré-lançamento do SDK do Azure para Python. Consulte o registo de alterações para a versão de pré-visualização mais recente que suporta a ingestão de escopos ACL e RBAC.
• Pacote de pré-lançamento do SDK do Azure para .NET. Consulte o registo de alterações para a versão de pré-visualização mais recente que suporta a ingestão de escopos ACL e RBAC.
• Pacote de pré-lançamento do SDK do Azure para Java. Consulte o registo de alterações para a versão de pré-visualização mais recente que suporta a ingestão de escopos ACL e RBAC.

Para a abordagem do modelo push:

1. Confirme que o seu esquema de índice foi criado com um SDK de pré-visualização ou pré-lançamento e que o esquema tem filtros de permissões.
2. Considere usar o Microsoft Graph SDK para obter identidades de grupo ou utilizador.
3. Use a API Index Documents ou SDK do Azure equivalente para empurrar documentos e os seus metadados de permissões associados para o índice de pesquisa.

Para a abordagem de indexador do modelo pull da ADLS Gen2 ou da fonte de conhecimento Blob (ADLS Gen2):

1. Verifique se os ficheiros no diretório estão protegidos usando o modelo de controlo de acesso ADLS Gen2.
2. Use Indexers - Create (REST API), Knowledge Sources - Create (REST API), ou uma API SDK do Azure equivalente para criar o indexador, índice e fonte de dados.

Se o seu conjunto de competências fragmentar os documentos em blocos, como acontece com a competência Text Split para vetorização integrada, os campos de metadados de permissão passam dos mapeamentos de campos do indexador para as projeções do índice. Consulte Escolher onde preencher os campos de ACL.

Padrão de ingestão de permissões ACL básicas para SharePoint no Microsoft 365 (visualização prévia)

Para conteúdos indexados do SharePoint, o Pesquisa de IA do Azure pode armazenar permissões de origem como metadados e usá-las para filtrar os resultados das consultas. Pode aceder a esta funcionalidade em pré-visualização através do SharePoint no indexador Microsoft 365 e da API REST mais recente ou de um pacote equivalente de SDK de pré-visualização.

Para requisitos de permissões, relações de grupo suportadas, sincronização de permissões e limitações, consulte Usar um indexador SharePoint para ingerir metadados de permissões.

Se o seu conjunto de competências divide documentos em blocos (por exemplo, com a competência Text Split para vetorização integrada), os campos ACL passam dos mapeamentos de campos do indexador para as projeções do índice. Consulte Escolher onde preencher os campos de ACL.

Padrão para etiquetas de sensibilidade do Microsoft Purview (pré-visualização)

Quando ativa a ingestão de rótulos, o Pesquisa de IA do Azure extrai metadados de sensibilidade das fontes de dados suportadas. Estas fontes de dados incluem Armazenamento de Blobs do Azure, Azure Data Lake Storage Gen2 (ADLS Gen2), SharePoint em Microsoft 365 e Microsoft OneLake. As etiquetas extraídas são armazenadas no índice juntamente com o conteúdo do documento.

No momento da consulta, o Pesquisa de IA do Azure verifica o rótulo de sensibilidade de cada documento, o token Microsoft Entra do utilizador e as políticas Purview da organização para determinar o acesso. O sistema devolve documentos apenas se a identidade do utilizador e as permissões baseadas em rótulos permitirem o acesso sob as políticas Purview configuradas.

Este padrão inclui os seguintes componentes:

• Configure o seu índice, fonte de dados e indexador (para fins de agendamento) usando a mais recente API REST de pré-visualização ou um SDK de pré-visualização que suporte a ingestão de rótulos Purview.
• Ative uma identidade gerida atribuída pelo sistema no seu serviço de pesquisa. As identidades geridas atribuídas ao utilizador não são suportadas para a extração de etiquetas do Purview — a própria identidade do serviço tem de ter as permissões elevadas do Purview. Em seguida, peça ao administrador global do inquilino ou ao administrador de funções privilegiadas para conceder o acesso necessário, de modo a permitir que o serviço de pesquisa se autentique no Microsoft Purview e extraia os metadados dos rótulos.
• Aplique etiquetas de sensibilidade aos documentos antes de indexar para que o sistema as possa reconhecer e preservar durante a ingestão.
• No momento da consulta, anexe um token de Microsoft Entra válido através do cabeçalho x-ms-query-source-authorization a cada pedido de consulta. O Pesquisa de IA do Azure avalia o token e os metadados associados às etiquetas para impor controlo de acesso baseado em etiquetas.

A aplicação do rótulo de sensibilidade Purview limita-se a cenários de inquilino único e requer autenticação RBAC. Durante a pré-visualização, é suportado apenas através da API REST e dos SDKs do Azure. As APIs de Autocomplete e Sugestão não estão atualmente disponíveis para índices habilitados pelo Purview.

Onde os rótulos de sensibilidade são apresentados

Antes de o sistema poder impor etiquetas na consulta ou devolvê-las nas respostas de recuperação, deve primeiro sincronizar os metadados da etiqueta no índice. Ambos os caminhos de consumo descritos nesta secção dependem deste passo de sincronização. Pode sincronizar etiquetas configurando um indexador Pesquisa de IA do Azure diretamente contra uma fonte de dados suportada, ou ativando a opção equivalente de ingestão ao criar uma fonte de conhecimento. Em ambos os casos, o seu ambiente tem de cumprir os pré-requisitos de configuração da sincronização dos metadados do rótulo de confidencialidade (identidade gerida, RBAC no serviço de pesquisa e as permissões necessárias do Microsoft Purview e da origem de dados). Para a configuração completa do indexador, veja Utilize indexadores do Pesquisa de IA do Azure para ingerir etiquetas de confidencialidade do Microsoft Purview. Para a ingestão orientada pela fonte de conhecimento, defina ingestionPermissionOptions para incluir sensitivityLabel durante a criação da fonte de conhecimento.

Depois de sincronizar etiquetas, dois caminhos de consulta consomem os mesmos metadados indexados de etiquetas. Escolha o caminho que corresponda à forma como a sua aplicação chama o Pesquisa de IA do Azure:

• API de consulta direta (/docs/search): Anexe o token Microsoft Entra do utilizador em x-ms-query-source-authorization. Os administradores também podem submeter pedidos de acesso de leitura elevado para investigações sujeitas a auditoria. Para configuração e exemplos, veja Aplicação em tempo de consulta das etiquetas de sensibilidade Microsoft Purview.

• Fontes de conhecimento e recuperação por agentes (MCP): Defina ingestionPermissionOptions para incluir sensitivityLabel na origem de conhecimento. A ação de recuperação e a ferramenta MCP knowledge_base_retrieve retornam por referência sensitivityLabelInfo e nível metadata.responseSensitivityLabelInfo de resposta que os clientes podem usar para exibir banners e aplicação de políticas. Para configuração, consulte Criação de fonte de conhecimento e Inspecção dos metadados da etiqueta de sensibilidade na recuperação de respostas.

Se a fonte de conhecimento apontar para um índice fragmentado, como, por exemplo, um índice preenchido através de vetorização integrada ou de uma competência personalizada de divisão de texto, o conjunto de competências também tem de projetar a etiqueta de sensibilidade para cada linha de segmento. Sem esta projeção, as referências ao nível dos blocos não são filtradas.

Para mais informações, consulte Use os indexadores do Pesquisa de IA do Azure para usar as Etiquetas de Sensibilidade do Microsoft Purview.

Impor permissões ao nível do documento no momento da consulta

A imposição de consultas baseada em tokens é uma capacidade transversal que se aplica aos âmbitos de ACL e RBAC do tipo POSIX, aos rótulos de confidencialidade do Microsoft Purview e aos padrões de ACL do SharePoint no Microsoft 365. Ao utilizar consultas nativas baseadas em tokens, o Pesquisa de IA do Azure valida o token Microsoft Entra do utilizador em cada pedido e reduz os conjuntos de resultados apenas aos documentos que o utilizador está autorizado a ler de acordo com as ACLs dos documentos, desde que os metadados das ACLs do documento estejam sincronizados com o índice.

Quando anexa o token do utilizador a um pedido de consulta através do cabeçalho x-ms-query-source-authorization, Pesquisa de IA do Azure:

1. Extrai as declarações de utilizador, grupo e escopo do token.
2. Compara essas reivindicações com os metadados de permissão armazenados juntamente com documentos indexados (entradas ACL, escopos RBAC, atribuições de rótulos Purview ou ACLs do SharePoint).
3. Devolve apenas documentos cujos metadados de permissão sincronizados concedem acesso ao chamador.

A aplicação de políticas em tempo de consulta avalia as declarações do Microsoft Entra do autor da chamada com os metadados de permissões já armazenados no índice. As alterações de permissões no sistema de origem (membros de grupos Microsoft Entra, ACLs ADLS Gen2, atribuições de etiquetas Purview ou ACLs do SharePoint) só são refletidas nos resultados de pesquisa depois de esses metadados serem sincronizados com o índice através do mecanismo específico da fonte, por exemplo, uma execução subsequente do indexador, uma atualização push-API ou uma atualização orientada pelo Purview. Para o SharePoint, as alterações às ACL em itens com permissões exclusivas são detetadas de forma incremental em cada execução bem-sucedida do indexador, a partir da API REST 2026-05-01-preview, enquanto as alterações herdadas de âmbitos superiores (site, biblioteca, lista ou pasta) requerem uma atualização explícita. Para mais informações, consulte Sincronizar permissões entre conteúdo indexado e fonte.

Para os passos de implementação de consultas de ponta a ponta, veja Query-time ACL and RBAC enforcement in Pesquisa de IA do Azure.

Benefícios do controlo de acesso ao nível de documentos

O controlo de acesso nativo ao nível de documentos no Pesquisa de IA do Azure oferece vantagens concretas em relação ao filtro do lado da aplicação:

• Elimina código personalizado para permissões: Não é preciso implementar a resolução de grupos aninhados, o percurso multinível de ACLs nem a filtragem após a consulta na sua aplicação. O Pesquisa de IA do Azure trata da comparação e filtragem durante a execução da consulta.
• Alinha-se com os controlos de conformidade existentes: Reutilizar metadados de permissões de Microsoft Entra, Microsoft Purview e SharePoint ajuda a manter os resultados de pesquisa alinhados com o sistema de identidade fonte. Revise o modelo de sincronização de permissões para cada fonte para compreender as suas limitações.
• Respeita as permissões de origem após cada sincronização da ACL: Para abordagens baseadas em tokens (ACL, âmbitos RBAC, etiquetas do Purview, ACLs do SharePoint), a imposição no momento da consulta utiliza os metadados de permissões que o mecanismo de sincronização documentado e específico da origem (execução do indexador, atualização através da API push ou atualização do Purview) já escreveu no índice.
• Melhora o desempenho em comparação com a limitação dos resultados após a consulta: Filtrar no pipeline de pesquisa é mais rápido do que carregar conjuntos maiores de resultados para a aplicação e limitá-los aí, especialmente quando o volume de consultas é elevado.
• Reutiliza a sua infraestrutura de identidade existente: o Microsoft Entra e as identidades do SharePoint continuam a ser a fonte fidedigna para as decisões de acesso, o que reduz a duplicação de identidades e a sobrecarga operacional de manter um repositório de permissões paralelo.

Tutoriais e exemplos

Explore o controlo de acesso ao nível de documentos no Pesquisa de IA do Azure com mais artigos e exemplos.

• Tutorial: Indexar metadados de permissões ADLS Gen2 usando um indexador
• azure-search-rest-samples/acl
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API
• azure-search-python-samples/Quickstart-Document-Permissions-Pull-API
• Aplicação de demonstração: Ingerir e respeitar rótulos de sensibilidade

Conteúdo relacionado

• Como indexar permissões ao nível do documento usando a API push
• Como indexar permissões ao nível do documento usando o indexador ADLS Gen2
• Como indexar permissões ao nível do documento usando a SharePoint no indexador Microsoft 365
• Como indexar etiquetas de sensibilidade usando indexadores
• Como consultar um índice habilitado por etiquetas de sensibilidade
• Como consultar usando permissões baseadas em tokens Microsoft Entra