Compartilhar via

Controle de acesso no nível do documento no Azure AI Search

O Azure AI Search 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 a construção de sistemas de IA seguros com agentes autônomos que fundamentam dados, aplicativos de Geração Aumentada por Recuperação (RAG) e soluções de pesquisa corporativa que exigem verificações de autorização no nível do documento.

Abordagens para controle de acesso no nível do documento

Abordagem Descrição
Filtros de segurança Comparação de cadeias de caracteres. 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) A entidade de segurança do Microsoft Entra por trás do token de consulta é comparada aos metadados de permissão de documentos retornados nos resultados da pesquisa, excluindo todos os documentos que não correspondam às permissões. As permissões de ACL (Listas de Controle de Acesso) se aplicam aos diretórios e arquivos 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 interno para o acesso baseado em identidade no documento está em versão prévia, disponível nas APIs REST e na versão prévia dos pacotes do SDK do Azure que fornecem o recurso. Verifique o log de alterações do pacote do SDK em busca de evidências de suporte ao recurso.
Rótulos de confidencialidade do Microsoft Purview (versão prévia) O indexador extrai rótulos de confidencialidade definidos no Microsoft Purview de fontes de dados com suporte (Armazenamento de Blobs do Azure, ADLS Gen2, SharePoint no Microsoft 365, OneLake). Esses rótulos são armazenados como metadados e avaliados no momento da consulta para aplicar o controle de acesso do usuário com base em tokens do Microsoft Entra e atribuições de política do Purview. Essa abordagem alinha a autorização do Azure AI Search com o modelo de Proteção de Informações da Microsoft da sua empresa.
AcLs do SharePoint no Microsoft 365 (versão prévia) Quando configurados, os indexadores do Azure AI Search extraem permissões de documento do SharePoint diretamente nas ACLs do Microsoft 365 durante a ingestão inicial. As verificações de acesso usam associações de usuários e grupos do Microsoft Entra. Os tipos de grupo com suporte incluem grupos de segurança do Microsoft Entra, grupos do Microsoft 365 e grupos de segurança habilitados para email. Os grupos do SharePoint ainda não têm suporte na versão prévia.

Padrão para filtragem de segurança usando filtros

Para cenários em que a integração de escopos ACL/RBAC nativos não é viável, recomendamos filtros de cadeia de segurança para limitar os 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 associadas.
  • 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 autor da chamada 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 garantir que o índice e a consulta tenham 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 que não são da Microsoft. Para obter mais informações sobre essa abordagem, consulte filtros de segurança para cortar resultados no Azure AI Search.

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 afiliados a documentos que você deseja indexar e consultar.

Contêineres do Azure Data Lake Storage (ADLS) 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 o conteúdo protegido por ACL, recomendamos 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, o Azure AI Search verifica duas coisas:

  • Primeiro, ele verifica a permissão Leitor de Dados do Índice de Pesquisa, que permite que seu 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, você pode usar a API do modelo de push, enviando qualquer documento JSON para o índice de pesquisa, em que o payload inclui um campo de cadeia que fornece ACLs semelhantes ao 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 maneira como você recupera permissões de ACL varia dependendo se você está carregando 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. Verifique se o esquema de índice também 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 do Microsoft Graph para obter identidades de grupo ou de usuário.
  3. Use o Indexar Documentos ou a API equivalente do SDK do Azure para inserir documentos e seus metadados de permissão associados no índice de pesquisa.

Para a abordagem do indexador ADLS Gen2 no modelo de spull ou para a fonte de conhecimento do 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 a API REST Criar Indexador, a API REST Criar Fonte de Conhecimento ou uma API equivalente do SDK do Azure para criar o indexador, o índice e a fonte de dados.

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

Para conteúdo do SharePoint no Microsoft 365, o Azure AI Search pode aplicar permissões no nível do documento com base em ACLs do SharePoint. Essa integração promove que somente usuários ou grupos com acesso ao documento de origem no SharePoint possam recuperá-lo nos resultados da pesquisa, assim que as permissões forem sincronizadas no índice. As permissões são aplicadas ao índice durante a ingestão inicial do documento.

O suporte à ACL do SharePoint está disponível em versão prévia por meio do indexador do SharePoint usando a API REST 2025-11-01-preview ou o SDK com suporte. O indexador extrai os metadados de permissão de arquivos e itens de uma lista e os preserva no índice de pesquisa, onde são usados para impor o controle de acesso no momento da consulta.

O padrão inclui os seguintes componentes:

  • Use o indexador do SharePoint no Microsoft 365 com permissões de aplicativo para ler o conteúdo do site do SharePoint e permissões completas para ler ACLs. Siga as instruções de instalação de ACL do indexador do SharePoint para habilitação e limitações.
  • Durante a indexação inicial, as entradas de ACL do SharePoint (usuários e grupos) são armazenadas como metadados de permissão no índice de pesquisa.
  • Para indexação incremental de ACLs, examine os mecanismos disponíveis de ressincronização de ACLs do SharePoint durante a visualização pública.
  • No momento da consulta, a Pesquisa de IA do Azure verifica a entidade de segurança do Microsoft Entra no token de consulta em relação aos metadados de ACL do SharePoint armazenados no índice. Ele exclui todos os documentos que o chamador não está autorizado a acessar.

Durante a visualização, somente os seguintes tipos principais têm suporte nas ACLs do SharePoint:

  • Contas de usuário do Microsoft Entra
  • Grupos de segurança do Microsoft Entra
  • Grupos do Microsoft 365
  • Grupos de segurança habilitados para email

Não há suporte para grupos do SharePoint na versão prévia.

Para obter detalhes de configuração e limitações completas, consulte Como indexar o SharePoint em permissões de nível de documento do Microsoft 365 (versão prévia).

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

A Pesquisa de IA do Azure pode ingerir e impor rótulos de confidencialidade do Microsoft Purview para o controle de acesso no nível do documento, estendendo as políticas de proteção de informações do Microsoft Purview para seus aplicativos de pesquisa e recuperação.

Quando a ingestão de rótulos está habilitada, o Azure AI Search extrai metadados de sensibilidade de fontes de dados compatíveis. Estes 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, o Azure AI Search verifica o rótulo de confidencialidade de cada documento, o token do Microsoft Entra do usuário e as políticas do Purview da organização para determinar o acesso. Os documentos serão retornados somente se as permissões baseadas em rótulo e identidade do usuário permitirem o acesso nas políticas configuradas do Purview.

O padrão inclui os seguintes componentes:

  • Configure seu índice, fonte de dados e indexador (para fins de agendamento) usando a API REST 2025-11-01-preview ou um SDK correspondente que dá suporte à ingestão de rótulos do Purview.
  • Habilite uma identidade gerenciada atribuída pelo sistema ao serviço de pesquisa. Em seguida, peça ao administrador global do locatário ou ao administrador de funções com privilégios para conceder o acesso necessário, para que o serviço de pesquisa possa acessar com segurança o Microsoft Purview e extrair metadados de rótulo.
  • Aplique rótulos de confidencialidade a documentos antes da indexação para que possam ser reconhecidos e preservados durante a ingestão.
  • No momento da consulta, anexe um token válido do Microsoft Entra por meio do cabeçalho x-ms-query-source-authorization a cada solicitação de consulta. O Azure AI Search avalia o token e os metadados de rótulo associados para impor o controle de acesso baseado em rótulo.

A imposição de rótulo de confidencialidade do Purview é limitada a cenários de locatário único, requer autenticação RBAC e, durante a visualização pública, há suporte apenas por meio da API REST ou do SDK. O preenchimento automático e as APIs de sugestão não estão disponíveis para índices habilitados para Purview no momento.

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

Com a consulta nativa baseada em token, a Pesquisa de IA do Azure valida o token do Microsoft Entra do usuário, limitando os conjuntos de resultados para incluir apenas os documentos que o usuário está autorizado a acessar.

Você pode realizar o corte automático anexando o token do Microsoft Entra do usuário à sua requisição de consulta. Para obter mais informações, confira ACL em tempo de consulta e imposição de RBAC 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 é fundamental para proteger informações confidenciais em aplicativos controlados por IA. Ele ajuda as organizações a criar sistemas que se alinham com suas políticas de acesso, reduzindo o risco de expor dados não autorizados ou confidenciais. Ao integrar regras de acesso diretamente ao pipeline de pesquisa, os sistemas de IA podem fornecer respostas fundamentadas em informações seguras e autorizadas.

Ao transferir a responsabilidade pela aplicação de permissões para o Azure AI Search, os programadores podem se concentrar na criação de sistemas de recuperação e classificação de alta qualidade. Essa abordagem ajuda a reduzir a necessidade de lidar com grupos aninhados, gravar filtros personalizados ou cortar manualmente os resultados da pesquisa.

As permissões no nível do documento no Azure AI Search fornecem uma estrutura estruturada para impor controles de acesso que se alinham às políticas organizacionais. Usando ACLs baseadas no Microsoft Entra e funções RBAC, as organizações podem criar sistemas que dão suporte a conformidade robusta e promovem a confiança entre os usuários. Esses recursos internos reduzem a necessidade de codificação personalizada, oferecendo uma abordagem padronizada para a segurança no nível do documento.

Tutoriais e exemplos

Examine mais de perto o controle de acesso no nível do documento no Azure AI Search com mais artigos e exemplos.

Conteúdo relacionado

  • Last updated on