Controle de acesso no nível do documento no Pesquisa de IA do Azure 

Note

Pesquisa de IA do Azure  está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Importante

Recursos, funcionalidades ou propriedades marcados como (versão prévia) não são cobertos por um contrato de nível de serviço (SLA), não são recomendados para cargas de trabalho de produção e podem mudar ou ser restringidos antes da disponibilidade geral. Os termos de visualização do Pesquisa de IA do Azure  se aplicam a toda funcionalidade em visualização, seja autônoma ou parte de um recurso de disponibilidade geral.

Pesquisa de IA do Azure  dá suporte ao controle de acesso no nível do documento, permitindo que as organizações imponham permissões refinadas no nível do documento, desde a ingestão de dados até a execução da consulta. Essa capacidade é essencial para construir sistemas de agentes de IA seguros que fundamentam dados, aplicativos de geração aumentada por recuperação (RAG) e soluções de busca empresarial que exigem verificações de autorização no nível do documento.

Abordagens para controle de acesso no nível do documento

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

Abordagem Descrição
Filtros de segurança Comparação de strings. Seu aplicativo passa uma identidade de usuário ou grupo como uma cadeia de caracteres, que preenche um filtro em uma consulta, excluindo todos os documentos que não correspondem à cadeia de caracteres.

Os filtros de segurança são uma técnica para obter o controle de acesso no nível do documento. Essa abordagem não está associada a uma API para que você possa usar qualquer versão ou pacote.
Escopos ACL/RBAC semelhantes a POSIX (versão prévia) O principal de segurança do Microsoft Entra associado ao token de consulta é comparado com os metadados de permissão dos documentos retornados nos resultados de pesquisa, excluindo todos os documentos cujas permissões não correspondam. As permissões de ACL (lista de controle de acesso) se aplicam aos arquivos e diretórios do Azure Data Lake Storage (ADLS) Gen2. Os escopos do RBAC (controle de acesso baseado em função) se aplicam ao conteúdo do ADLS Gen2 e aos Blobs do Azure.

O suporte integrado para acesso baseado em identidade no nível do documento está em versão prévia, disponível em APIs REST e pacotes SDK do Azure em versão prévia que fornecem o recurso. Para obter evidências de suporte a recursos, verifique os detalhes de suporte à versão do SDK.
Rótulos de confidencialidade do Microsoft Purview (versão prévia) O indexador extrai rótulos de confidencialidade definidos em Microsoft Purview de fontes de dados com suporte (Armazenamento de Blobs do Azure, ADLS Gen2, SharePoint em Microsoft 365, OneLake). Esses rótulos são armazenados como metadados e avaliados no momento da consulta a fim de impor o acesso do usuário com base nos tokens do Microsoft Entra e nas atribuições de políticas do Purview. Os rótulos também aparecem em fontes de conhecimento e na resposta de recuperação agêntica, permitindo que agentes de IA e aplicativos de chat que consomem uma base de conhecimento recebam a mesma filtragem com reconhecimento dos rótulos. Essa abordagem alinha a autorização do Pesquisa de IA do Azure  com o modelo de Microsoft Proteção de Informações da sua empresa.
SharePoint em ACLs de Microsoft 365 (versão prévia) Os indexadores do Pesquisa de IA do Azure  extraem metadados de permissão do conteúdo compatível do SharePoint e usam esses metadados para verificações de acesso no momento da consulta. Para obter informações sobre conteúdo com suporte, principais, relações de grupo, comportamento de sincronização e permissões, consulte Usar um indexador do SharePoint para assimilar metadados de permissões.

Para fontes de conhecimento indexadas, ingestionPermissionOptions não é possível combinar com assetStore. Portanto, o serviço de imagem (versão prévia) não está disponível quando a ingestão de permissão no nível do documento nativo está habilitada.

Escolher uma abordagem

Use os critérios a seguir para identificar a abordagem que melhor se adapta aos requisitos de fonte de dados, modelo de identidade e conformidade.

Scenario Abordagem recomendada Por que
Sistema de identidade personalizado, framework de segurança que não seja da Microsoft ou qualquer índice baseado em push. Filtros de segurança Independente de API, amplamente disponível e baseado em correspondência simples de strings.
Conteúdo no ADLS Gen2 ou no Armazenamento de Blobs do Azure com ACLs ou atribuições de RBAC já existentes. Escopos de ACL/RBAC semelhantes ao POSIX Integração nativa do Microsoft Entra; a imposição de tempo de consulta usa metadados de permissão gravados no índice pelo mecanismo de sincronização documentado.
Conteúdo corporativo já regido por políticas de proteção de informações Microsoft Purview. Rótulos de confidencialidade do Microsoft Purview Reutiliza atribuições de política e classificação centralizadas em Pesquisa de IA do Azure .
Conteúdo proveniente de SharePoint em Microsoft 365 (bibliotecas, listas, páginas de site do ASPX). ACLs do SharePoint no Microsoft 365 Respeita as permissões de SharePoint nativas, incluindo grupos de sites SharePoint.

Padrão de corte de segurança usando-se filtros

Para cenários em que a integração de escopos nativos de ACL/RBAC não for viável, use filtros de cadeia de caracteres de segurança para cortar resultados com base em critérios de exclusão. O padrão inclui os seguintes componentes:

  • Para armazenar identidades de usuário ou grupo, crie um campo de cadeia de caracteres no índice.
  • Carregue o índice usando documentos de origem que incluem ACLs associados.
  • Inclua uma expressão de filtro na lógica de consulta para correspondência na cadeia de caracteres.
  • No momento da consulta, obtenha a identidade do chamador.
  • Passe a identidade do chamador como a cadeia de caracteres de filtro.
  • Os resultados são cortados para excluir todas as correspondências que não incluem a cadeia de caracteres de identidade de usuário ou grupo.

Você pode usar APIs de modelo push ou pull. Como essa abordagem é independente da API, você só precisa confirmar se o índice e a consulta têm cadeias de caracteres (identidades) válidas para a etapa de filtragem.

Essa abordagem é útil para sistemas com modelos de acesso personalizados ou estruturas de segurança não Microsoft. Para obter mais informações sobre essa abordagem, consulte os filtros Security para cortar resultados em Pesquisa de IA do Azure .

Padrão para suporte nativo para permissões de escopo de ACL e RBAC semelhantes a POSIX (versão prévia)

O suporte nativo é baseado em usuários e grupos do Microsoft Entra associados aos documentos que você deseja indexar e consultar.

os contêineres do ADLS (Azure Data Lake Storage) Gen2 dão suporte a ACLs no contêiner e em arquivos. Para o ADLS Gen2, a preservação do escopo do RBAC no nível do documento tem suporte nativo quando você usa um indexador ADLS Gen2 ou uma fonte de conhecimento de Blob (dá suporte ao ADLS Gen2) e uma API de visualização para ingerir conteúdo. Para os blobs do Azure que usam o indexador de blob do Azure ou a fonte de conhecimento, a preservação do escopo do RBAC é feita no nível do contêiner.

Para conteúdo protegido por ACL, use o acesso de grupo sobre o acesso de usuário individual para facilitar o gerenciamento. O padrão inclui os seguintes componentes:

Seu aplicativo cliente recebe permissões de leitura para o índice por meio da função Leitor de Dados do Índice de Pesquisa ou Colaborador de Dados de Índice de Pesquisa . O acesso no momento da consulta é determinado por metadados de permissão de usuário ou grupo no conteúdo indexado. Consultas que incluem um filtro de permissão passam um token de usuário ou grupo como x-ms-query-source-authorization no cabeçalho da solicitação. Quando você usa filtros de permissão no momento da consulta, Pesquisa de IA do Azure  verifica duas coisas:

  • Primeiro, ele verifica a permissão Pesquisa do Leitor de Dados de Índice que permite que o aplicativo cliente acesse o índice.

  • Em segundo lugar, dado o token extra na solicitação, ele verifica se há permissões de usuário ou grupo em documentos que são retornados nos resultados da pesquisa, excluindo qualquer um que não corresponda.

Para inserir metadados de permissão no índice, use a API do modelo de envio, enviando documentos JSON ao índice de pesquisa, em que a carga útil inclui um campo de cadeia de caracteres que fornece ACLs semelhantes às do POSIX para cada documento. A diferença importante entre essa abordagem e a filtragem de segurança é que os metadados do filtro de permissão no índice e na consulta são reconhecidos como autenticação do Microsoft Entra ID, enquanto a solução alternativa de filtragem de segurança é uma simples comparação de cadeia de caracteres. Além disso, você pode usar o SDK do Graph para recuperar as identidades.

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

Recuperar metadados de permissões de ACL durante o processo de ingestão de dados (versão prévia)

A forma como você recupera as permissões de ACL varia dependendo se você estiver enviando um payload de documentos ou usando o indexador ADLS Gen2.

Comece com uma API de visualização que fornece o recurso:

Para a abordagem do modelo de push:

  1. Confirme se o esquema de índice foi criado com um SDK de versão prévia ou pré-lançamento e se o esquema tem filtros de permissão.
  2. Considere usar o SDK Microsoft Graph para obter identidades de grupo ou de usuário.
  3. Use o Index Documents ou a API de SDK do Azure equivalente para fazer o upload de documentos e seus metadados de permissão associados para o índice de pesquisa.

Para a abordagem do indexador ADLS Gen2 no modelo de extração ou para a origem de conhecimento de Blob (ADLS Gen2):

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

Se o seu conjunto de habilidades dividir documentos em partes, como com a habilidade Divisão de Texto para vetorização integrada, os campos de metadados de permissão passam dos mapeamentos de campos do indexador para as projeções de índice. Veja Escolher onde preencher os campos de ACL.

Padrão para o SharePoint na ingestão de permissões básicas de ACL básica do Microsoft 365 (versão prévia)

Para conteúdo de SharePoint indexado, Pesquisa de IA do Azure  pode armazenar permissões de origem como metadados e usá-las para filtrar os resultados da consulta. Você pode acessar essa funcionalidade em versão prévia por meio do SharePoint no indexador Microsoft 365 e na API REST mais recente ou em um pacote SDK de visualização equivalente.

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

Se o seu conjunto de habilidades fragmenta documentos (por exemplo, com a habilidade Divisão de Texto para vetorização integrada), os campos ACL são movidos dos mapeamentos de campo do indexador para as projeções do índice. Veja Escolher onde preencher os campos de ACL.

Padrão para rótulos de confidencialidade de Microsoft Purview (versão prévia)

Quando você habilita a ingestão de rótulos, a Pesquisa de IA do Azure extrai metadados de confidencialidade de fontes de dados com suporte. Essas fontes de dados incluem Armazenamento de Blobs do Azure, Azure Data Lake Storage Gen2 (ADLS Gen2), SharePoint no Microsoft 365 e Microsoft OneLake. Os rótulos extraídos são armazenados no índice junto com o conteúdo do documento.

No momento da consulta, Pesquisa de IA do Azure  verifica o rótulo de confidencialidade de cada documento, o token de Microsoft Entra do usuário e as políticas do Purview da organização para determinar o acesso. O sistema retornará documentos somente se as permissões baseadas em rótulo e identidade do usuário permitirem acesso nas políticas configuradas do Purview.

Esse padrão inclui os seguintes componentes:

  • Configure o índice, a fonte de dados e o indexador (para fins de agendamento) usando a API REST de versão prévia mais recente ou um SDK de versão prévia que dá suporte à ingestão de rótulos do Purview.
  • Habilite uma identidade gerenciada atribuída pelo sistema em seu serviço de pesquisa. Não há suporte para identidades gerenciadas atribuídas pelo usuário para extração de rótulos do Purview – a própria identidade do serviço deve conter as permissões elevadas do Purview. Em seguida, faça com que o administrador global do locatário ou o administrador de funções com privilégios conceda o acesso necessário para permitir que o serviço de pesquisa se autentique com Microsoft Purview e extraia metadados de rótulo.
  • Aplique rótulos de confidencialidade a documentos antes da indexação para que o sistema possa reconhecê-los e preservá-los durante a ingestão.
  • No momento da consulta, anexe um token de Microsoft Entra válido por meio do cabeçalho x-ms-query-source-authorization a cada solicitação de consulta. Pesquisa de IA do Azure  avalia o token e os metadados de rótulo associados para impor o controle de acesso baseado em rótulo.

A aplicação do rótulo de confidencialidade do Purview é limitada a cenários de locatário único e exige autenticação RBAC. Durante a prévia, ele é compatível apenas por meio da API REST e dos SDKs do Azure. As APIs Autocomplete e Suggest não estão disponíveis atualmente para índices com Purview habilitado.

Onde os rótulos de confidencialidade são exibidos

Antes que o sistema possa impor rótulos no momento da consulta ou devolvê-los em respostas de recuperação, primeiro você deve sincronizar os metadados do rótulo no índice. Ambos os caminhos de consumo descritos nesta seção dependem dessa etapa de sincronização. Você pode sincronizar rótulos configurando um indexador Pesquisa de IA do Azure  diretamente em uma fonte de dados com suporte ou habilitando a opção de ingestão equivalente ao criar uma fonte de conhecimento. Em ambos os casos, seu ambiente deve atender aos pré-requisitos de configuração da sincronização de metadados do rótulo de confidencialidade (identidade gerenciada, RBAC no serviço de busca e as permissões necessárias do Microsoft Purview e da fonte de dados). Para configurar o indexador de ponta a ponta, consulte Usar os indexadores da Pesquisa de IA do Azure para assimilar os rótulos de confidencialidade do Microsoft Purview. Para ingestão orientada pela fonte de conhecimento, defina ingestionPermissionOptions para incluir sensitivityLabel durante a criação da fonte de conhecimento.

Depois de sincronizar rótulos, dois caminhos de consulta consomem os mesmos metadados de rótulo indexados. Escolha o caminho que corresponde à forma como seu aplicativo chama Pesquisa de IA do Azure :

Se a fonte de conhecimento apontar para um índice fragmentado, como aquele populado por vetorização integrada ou por uma habilidade personalizada de Divisão de Texto, o conjunto de habilidades também deverá projetar o rótulo de confidencialidade em cada linha de fragmento. Sem essa projeção, as referências em nível de bloco não são filtradas.

Para obter mais informações, confira Usar indexadores da Pesquisa de IA do Azure para ingerir rótulos de confidencialidade do Microsoft Purview.

Impor permissões no nível do documento no momento da consulta (versão prévia)

A aplicação de restrições de consulta com base em token é uma capacidade transversal que se aplica aos escopos de ACL no estilo POSIX e de RBAC, aos rótulos de confidencialidade do Microsoft Purview e aos padrões de ACLs do SharePoint no Microsoft 365. Ao usar consulta nativa baseada em token, o Pesquisa de IA do Azure  valida o token do Microsoft Entra do chamador em cada solicitação e restringe os conjuntos de resultados de modo a incluir apenas os documentos que o chamador está autorizado a ler de acordo com as ACLs dos documentos, desde que os metadados de ACL dos documentos estejam sincronizados com o índice.

Quando você anexa o token do usuário a uma solicitação de consulta por meio do cabeçalho x-ms-query-source-authorization, Pesquisa de IA do Azure :

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

A imposição de tempo de consulta avalia as declarações do Microsoft Entra do chamador em relação aos metadados de permissão que já estão armazenados no índice. As alterações de permissão no sistema de origem (associação a grupos do Microsoft Entra, ACLs do ADLS Gen2, atribuições de rótulos do Purview ou ACLs do SharePoint) só são refletidas nos resultados de pesquisa depois que esses metadados são sincronizados com o índice por meio do mecanismo específico da origem, por exemplo, uma execução subsequente do indexador, uma atualização via API de push ou uma atualização controlada pelo Purview. Para o SharePoint, as alterações de ACL em itens com permissões exclusivas são detectadas de forma incremental em cada execução bem-sucedida do indexador na API REST 2026-05-01-preview, enquanto as alterações herdadas de escopos superiores (site, biblioteca, lista ou pasta) exigem uma atualização explícita. Para obter mais informações, consulte Sincronizar permissões entre conteúdo indexado e de origem.

Para ver as etapas de implementação de consultas de ponta a ponta, consulte Aplicação de ACL e RBAC em tempo de consulta na Pesquisa de IA do Azure.

Benefícios do controle de acesso no nível do documento

O controle de acesso no nível do documento nativo no Pesquisa de IA do Azure  oferece vantagens concretas em relação à filtragem do lado do aplicativo:

  • Elimina o código de permissões personalizado: você não precisa implementar a resolução de grupos aninhados, o percurso de ACLs multinível ou a filtragem após a consulta no seu aplicativo. Pesquisa de IA do Azure  manipula a comparação e a filtragem durante a execução da consulta.
  • Alinha-se aos controles de conformidade existentes: Reutilizar os metadados de permissões do Microsoft Entra, do Microsoft Purview e do SharePoint ajuda a manter os resultados de pesquisa alinhados com o sistema de identidade de origem. Revise o modelo de sincronização de permissões de cada fonte para entender suas limitações.
  • Respeita as permissões da origem após cada sincronização de ACL: para abordagens baseadas em tokens (ACL, escopos de RBAC, rótulos do Purview, ACLs do SharePoint), a aplicação em tempo de consulta usa os metadados de permissão que o mecanismo de sincronização específico da origem documentado (execução do indexador, atualização via API push ou atualização do Purview) já gravou no índice.
  • Melhora o desempenho em comparação com o refinamento após a consulta: Filtrar dentro do pipeline de busca é mais rápido do que carregar conjuntos de resultados maiores no seu aplicativo e refiná-los ali, especialmente em altos volumes de consultas.
  • Reutilize sua infraestrutura de identidade existente: as identidades do Microsoft Entra e do SharePoint continuam sendo a fonte oficial para as decisões de acesso, o que reduz a duplicação de identidades e a sobrecarga operacional de manter um repositório paralelo de permissões.

Tutoriais e exemplos

Explore o controle de acesso no nível do documento em Pesquisa de IA do Azure  com mais artigos e exemplos.

Conteúdo relacionado

  • Last updated on