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

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:

• Crie um campo de cadeia de caracteres no índice para armazenar cadeias de caracteres de identidades de usuário ou grupo.
• Carregue o índice com documentos de origem que incluam um campo contendo as identidades.
• 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 baseia-se nas IDs de acesso de grupo e de usuário do Microsoft Entra afiliadas 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 o indexador ADLS Gen2 e uma API de visualização para ingerir conteúdo. Para blobs do Azure que usam o indexador de blobs do Azure, a preservação do escopo RBAC é feita no nível do contêiner.

Para conteúdo protegido por ACL, recomendamos IDs de acesso de grupo em vez de IDs de acesso de usuário para facilitar o gerenciamento. O padrão inclui os seguintes componentes:

• Comece com documentos ou arquivos que têm atribuições de ACL.
• Habilite filtros de permissão no índice.
• Adicione um filtro de permissão a um campo de cadeia de caracteres em um índice.
• Carregue o índice com documentos de origem que tenham ACLs associadas.
• Consulte o índice, adicionando ao cabeçalho da solicitaçãox-ms-query-source-authorization.

Seu aplicativo cliente tem permissões de leitura para o índice por meio do Leitor de Dados do Índice de Pesquisa, mas os metadados de permissão de usuário ou grupo no conteúdo indexado determinam o acesso no momento da consulta. 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 2 coisas:

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

-Segundo, considerando o token extra na solicitação, ele verifica se há permissões de usuário ou grupo em documentos 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 durante o processo de ingestão de dados

Como você recupera permissões varia conforme você está transmitindo um payload de documentos ou usando o indexador ADLS Gen2.

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

• API REST de versão prévia de 2025-08-01
• Pacote de pré-lançamento do SDK do Azure para Python
• Pacote de pré-lançamento do SDK do Azure para .NET
• Pacote de pré-lançamento do SDK do Azure para Java

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 IDs 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 pull:

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

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, consulte Imposição da 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 é 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.

• Tutorial: Indexar metadados de permissões do ADLS Gen2 usando um indexador
• azure-search-rest-samples/Quickstart-ACL
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API
• azure-search-python-samples/Quickstart-Document-Permissions-Pull-API

Conteúdo relacionado

• Como indexar permissões no nível do documento usando a API de push
• Como indexar permissões no nível do documento usando o indexador ADLS Gen2
• Como consultar usando permissões baseadas em token do Microsoft Entra