Partilhar via

Controle de acesso no nível de 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. Esse recurso é essencial para criar sistemas de IA seguros baseados em dados, aplicativos de geração de Retrieval-Augmented (RAG) e soluções de pesquisa corporativa que exigem validações de autorização ao nível do documento.

Abordagens para controle de acesso em nível de 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 quaisquer documentos que não correspondam na cadeia de caracteres.

Os filtros de segurança são uma técnica para obter controle de acesso no nível do documento. Essa abordagem não está vinculada a uma API para que você possa usar qualquer versão ou pacote.
Âmbitos ACL / RBAC semelhantes a POSIX (prévia) O princípio de segurança do Microsoft Entra por trás do token de consulta é comparado com os metadados de permissões dos documentos devolvidos nos resultados de pesquisa, excluindo quaisquer documentos que não coincidam nas permissões. As permissões das Listas de Controle de Acesso (ACL) aplicam-se aos diretórios e arquivos Gen2 do Azure Data Lake Storage (ADLS). Os escopos de controle de acesso baseado em função (RBAC) se aplicam ao conteúdo do ADLS Gen2 e aos blobs do Azure.

O suporte interno para acesso baseado em identidade no nível do documento está em visualização, disponível em APIs REST e em pacotes do SDK do Azure que fornecem o recurso. Certifique-se de verificar o log de alterações do pacote SDK para obter evidências de suporte a recursos.
Etiquetas de sensibilidade Microsoft Purview (pré-visualização) O Indexer extrai etiquetas de sensibilidade definidas no Microsoft Purview a partir de fontes de dados suportadas (Azure Blob Storage, ADLS Gen2, SharePoint em Microsoft 365, OneLake). Estes rótulos são armazenados como metadados e avaliados no momento da consulta para garantir o acesso do utilizador com base nos tokens Microsoft Entra e nas atribuições de políticas Purview. Esta abordagem alinha a autorização Azure AI Search com o modelo Microsoft Information Protection da sua empresa.
SharePoint em ACLs do Microsoft 365 (pré-visualização) Quando configurados, os indexadores Azure AI Search extraem permissões de documentos SharePoint diretamente nas ACLs do Microsoft 365 durante a ingestão inicial. As verificações de acesso utilizam a adesão de utilizadores e grupos do Microsoft Entra. Os tipos de grupos suportados incluem grupos de segurança Microsoft Entra, grupos Microsoft 365 e grupos de segurança com e-mail. Os grupos SharePoint ainda não são suportados na pré-visualização.

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 strings de segurança para refinar 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 documentos fonte que incluam Listas de Controle de Acesso (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 chamador como parâmetro da cadeia de filtro.
  • Os resultados são cortados para excluir quaisquer correspondências que não incluam a cadeia de caracteres de identidade do usuário ou grupo,

Você pode usar APIs de modelo push ou pull. Como essa abordagem é agnóstica em relação à 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 sejam da Microsoft. Para obter mais informações sobre essa abordagem, consulte Filtros de segurança para cortar resultados no Azure AI Search.

Modelo para suporte nativo a permissões de escopo ACL e RBAC semelhantes ao POSIX (pré-visualização)

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

Os contêineres Gen2 do Azure Data Lake Storage (ADLS) dão suporte a ACLs no contêiner e nos arquivos. 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 Azure usando o indexador Azure blob ou fonte de conhecimento, a preservação do âmbito RBAC está ao nível do contêiner.

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

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. As 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 usas filtros de permissões no momento da consulta, o Azure AI Search verifica duas coisas:

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

  • Em segundo lugar, com base no token extra fornecido no pedido, verifica as permissões de utilizador ou grupo em documentos que são retornados nos resultados da pesquisa, excluindo aqueles que não correspondem.

Para obter metadados de permissão no índice, você pode usar a API do modelo push, enviando quaisquer documentos JSON para o índice de pesquisa, onde a carga inclui um campo de cadeia de caracteres fornecendo ACLs semelhantes a 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 de ID do Microsoft Entra, enquanto a solução alternativa de filtragem de segurança é uma comparação de cadeia de caracteres simples. 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 se o seu código invocar uma API de pré-visualização para indexação.

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

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 visualização que fornece o recurso:

Para a abordagem do modelo push:

  1. Verifique se o esquema de índice também foi criado com um SDK de visualização ou pré-lançamento e se o esquema tem filtros de permissão.
  2. Considere usar o Microsoft Graph SDK para obter identidades de grupo ou utilizador.
  3. Use os Documentos de Índice ou a API equivalente do SDK do Azure para enviar documentos e seus metadados de permissão associados para o índice de pesquisa.

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

  1. Verifique se os arquivos no diretório estão protegidos usando o modelo de controle de acesso ADLS Gen2.
  2. Use a API REST do Create Indexer ou a API REST do Create Knowledge Source ou API Azure SDK equivalente para criar o indexador, o índice e a fonte de dados.

Modelo para a ingestão de permissões ACL básicas no SharePoint no Microsoft 365 (versão prévia)

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

Suporte para ACL do SharePoint está disponível em prévia através do indexador SharePoint usando a API REST 2025-11-01-preview ou SDK compatível. O indexador extrai metadados de permissão de ficheiros e itens de lista e preserva-os no índice de pesquisa, onde é usado para impor controlo de acesso no momento da consulta.

O padrão inclui os seguintes componentes:

  • Utilize o indexador do SharePoint no Microsoft 365 com permissões de aplicação para ler o conteúdo do site do SharePoint e permissões totais para ler as listas de controle de acesso (ACLs). Siga as instruções de configuração da ACL do indexador SharePoint para ativação e limitações.
  • Durante a indexação inicial, as entradas ACL do SharePoint (utilizadores e grupos) são armazenadas como metadados de permissão no índice de pesquisa.
  • Para indexação incremental das ACLs, consulte os mecanismos de resincronização das ACLs do SharePoint disponíveis durante a pré-visualização pública.
  • No momento da consulta, o Azure AI Search verifica o principal Microsoft Entra no token de consulta em relação aos metadados ACL do SharePoint armazenados no índice. Exclui quaisquer documentos a que o interlocutor não esteja autorizado a aceder.

Durante a pré-visualização, apenas os seguintes tipos principais são suportados nas ACLs do SharePoint:

  • Contas de utilizador Microsoft Entra
  • Grupos de segurança Microsoft Entra
  • Grupos do Microsoft 365
  • Grupos de segurança com capacidade de correio

Os grupos SharePoint não são suportados na versão de pré-visualização.

Para detalhes de configuração e limitações completas, veja Como indexar o SharePoint nas permissões ao nível de documento do Microsoft 365 (pré-visualização).

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

O Azure AI Search pode ingerir e aplicar etiquetas de sensibilidade Microsoft Purview para controlo de acesso ao nível de documentos, estendendo políticas de proteção de informação do Microsoft Purview para as suas aplicações de pesquisa e recuperação.

Quando a ingestão de etiquetas está ativada, o Azure AI Search extrai metadados de sensibilidade das fontes de dados suportadas. Estas incluem: Azure Blob Storage, Azure Data Lake Storage Gen2 (ADLS Gen2), SharePoint no 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 Azure AI Search verifica a etiqueta de sensibilidade de cada documento, o token Microsoft Entra do utilizador e as políticas Purview da organização para determinar o acesso. Os documentos só são devolvidos se a identidade do utilizador e as permissões baseadas em rótulos permitirem o acesso ao abrigo das políticas Purview configuradas.

O padrão inclui os seguintes componentes:

  • Configure o seu índice, fonte de dados e indexador (para fins de agendamento) usando a API REST preview de 2025-11-01-ou um SDK correspondente que suporte a ingestão de rótulos Purview.
  • Ative uma identidade gerida atribuída pelo sistema ao seu serviço de pesquisa. Depois, peça ao seu administrador global de inquilino ou administrador de funções privilegiadas para conceder o acesso necessário, para que o serviço de pesquisa possa aceder com segurança ao Microsoft Purview e extrair os metadados dos rótulos.
  • Aplique etiquetas de sensibilidade aos documentos antes de indexar para que possam ser reconhecidas e preservadas durante a ingestão.
  • No momento da consulta, anexe um token Microsoft Entra válido através do cabeçalho x-ms-query-source-authorization a cada pedido de consulta. O Azure AI Search avalia o token e os metadados associados às etiquetas para impor controlo de acesso baseado em etiquetas.

A aplicação de etiquetas de sensibilidade Purview está limitada a cenários de inquilino único, requer autenticação RBAC e, durante a pré-visualização pública, é suportada apenas através de API REST ou SDK. As APIs de preenchimento automático e sugestão não estão disponíveis para índices com suporte do Purview neste momento.

Para mais informações, consulte Utilize os indexadores do Azure AI Search para importar as etiquetas de sensibilidade do Microsoft Purview.

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

Com consultas baseadas em tokens nativas, o Azure AI Search valida o token Microsoft Entra de um usuário, cortando conjuntos de resultados para incluir apenas documentos que o usuário está autorizado a acessar.

Pode obter a redução automática ao anexar o token Microsoft Entra do utilizador ao seu pedido de consulta. Para mais informações, consulte Aplicação de ACL e RBAC durante a consulta no Azure AI Search.

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

O controle de acesso em nível de documento é fundamental para proteger informações confidenciais em aplicativos orientados por IA. Ele ajuda as organizações a criar sistemas que se alinham com suas políticas de acesso, reduzindo o risco de exposição de dados não autorizados ou confidenciais. Ao integrar as regras de acesso diretamente no pipeline de pesquisa, os sistemas de IA podem fornecer respostas baseadas em informações seguras e autorizadas.

Ao delegar a aplicação de permissões para o Azure AI Search, os desenvolvedores podem concentrar-se 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, escrever filtros personalizados ou cortar manualmente os resultados da pesquisa.

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

Tutoriais e exemplos

Dê uma olhada mais de perto no controle de acesso no nível de documento no Azure AI Search com mais artigos e exemplos.

Conteúdo relacionado

  • Last updated on