Usar um indexador ADLS Gen2 para ingerir metadados de permissão e filtrar os resultados da pesquisa com base nos direitos de acesso do usuário

O modelo de permissão no Azure Data Lake Storage (ADLS) Gen2 pode ser usado para acesso por usuário a diretórios ou arquivos específicos. A partir de 2025-05-01-preview, agora você pode incluir permissões de usuário junto com a ingestão de documentos no Azure AI Search e usar essas permissões para controlar o acesso aos resultados da pesquisa. Se um usuário não tiver permissões em um diretório ou arquivo específico no ADLS Gen2, esse usuário não terá acesso aos documentos correspondentes nos resultados da Pesquisa de IA do Azure.

Você pode usar as APIs por push para carregar e indexar metadados de conteúdo e permissão manualmente ou usar um indexador para automatizar a ingestão de dados. Este artigo se concentra na abordagem do indexador.

A abordagem do indexador baseia-se nessa base:

• O modelo de controle de acesso do ADLS Gen2 que fornece ACLs (listas de controle de acesso) e controle de acesso baseado em função (RBAC do Azure). Não há suporte para o Azure ABAC (controle de acesso baseado em atributo).

• Um indexador do Azure AI Search para ADLS Gen2 que recupera e ingere dados e metadados, incluindo filtros de permissão. Para obter suporte ao filtro de permissão, use a API REST de versão prévia mais recente ou um pacote de pré-lançamento de um SDK do Azure que dê suporte ao recurso.

• Um índice no Azure AI Search que contém os documentos ingeridos e as permissões correspondentes. Os metadados de permissão são armazenados como campos no índice. Para configurar consultas que respeitam os filtros de permissão, use a API REST de versão prévia mais recente ou um pacote de pré-lançamento de um SDK do Azure que dê suporte ao recurso.

Essa funcionalidade ajuda a alinhar as permissões no nível do documento no índice de pesquisa com os controles de acesso definidos no ADLS Gen2, permitindo que os usuários recuperem conteúdo de uma maneira que reflita suas permissões existentes.

Este artigo complementa dados de índice do ADLS Gen2 com informações específicas para a ingestão de permissões juntamente com o conteúdo do documento em um índice de busca do Azure AI.

Prerequisites

• Autenticação e autorização do Microsoft Entra ID. Serviços e aplicativos devem estar no mesmo locatário. Os usuários podem estar em locatários diferentes, desde que todos os locatários sejam do Microsoft Entra ID. As atribuições de função são usadas para cada conexão autenticada.

• Pesquisa de IA do Azure, qualquer região, mas é necessário ter uma camada faturável (básica ou superior) para dar suporte à identidade gerenciada. O serviço de pesquisa deve ser configurado para acesso baseado em função e deve ter uma identidade gerenciada (sistema ou usuário).

• Blobs do ADLS Gen2 em um namespace hierárquico, com permissões de usuário concedidas por meio de ACLs ou funções.

Limitations

• Os limites de atribuições de função do Azure e entradas de ACL no ADLS Gen2 impõem um número máximo de atribuições de função e entradas ACL.

• As categorias de identidades owning users, owning groups, Other (all), ACL não são suportadas durante a visualização pública. Em vez disso, use atribuições de named users e named groups.

• Os recursos do indexador a seguir não dão suporte à herança de permissão em documentos indexados provenientes do ADLS Gen2. Se você estiver usando qualquer um desses recursos em um conjunto de habilidades ou indexador, as permissões no nível do documento não estarão presentes no conteúdo indexado:

  • Habilidade da API Web personalizada
  • Competência de prompt do GenAI
  • Repositório de conhecimento
  • Cache de enriquecimento do indexador
  • Sessões de depuração

• No momento, não há suporte para essa funcionalidade no portal do Azure.

Suporte para o modelo de permissão

Esta seção compara os recursos de controle de acesso no nível do documento entre o ADLS Gen2 e o Azure AI Search. Ele destaca quais mecanismos de controle de acesso do ADLS Gen2 têm suporte ou são mapeados durante a integração com a Pesquisa de IA, ajudando você a entender como as permissões são impostas no nível do documento.

Sobre permissões hierárquicas de ACL

Os indexadores podem recuperar atribuições de ACL do contêiner especificado e todos os diretórios que levam a cada arquivo seguindo o fluxo de avaliação de acesso hierárquico do ADLS Gen2. As listas de acesso efetivas finais para cada arquivo são computadas e as diferentes categorias de acesso são indexadas nos campos de índice correspondentes.

Por exemplo, em cenários comuns do ADLS Gen2 relacionados a permissões, como o caminho do arquivo /Oregon/Portland/Data.txt.

O indexador busca ACLs de cada contêiner e diretório, resolve-as no acesso efetivo retido de níveis mais baixos e continua esse processo até determinar o acesso efetivo para cada arquivo.

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

Configurar ADLS Gen2

Um indexador poderá recuperar ACLs em uma conta de armazenamento se os critérios a seguir forem atendidos. Para obter mais informações sobre atribuições de ACL, consulte as atribuições de ACL do ADLS Gen2.

Authorization

Para a execução do indexador, a identidade do serviço de pesquisa deve ter permissão de Leitor de Dados de Armazenamento de Blobs.

Se você estiver testando localmente, também deverá ter uma atribuição de função Leitor de Dados de Armazenamento de Blobs. Para obter mais informações, consulte Conectar-se ao Armazenamento do Azure usando uma identidade gerenciada.

Permissões de contêiner raiz:

1. Atribuir todos os conjuntos Group e User (entidades de segurança) no contêiner raiz / com permissões Read e Execute.

2. Certifique-se de que ambos Read e Execute sejam adicionados como "Permissões padrão" para que sejam propagados automaticamente para arquivos e diretórios recém-criados.

Propagar permissões na hierarquia de arquivos

Embora novos diretórios e arquivos herdem permissões, os diretórios e arquivos existentes não herdam automaticamente essas atribuições.

Use a ferramenta ADLS Gen2 para aplicar ACLs recursivamente para a propagação de atribuições no conteúdo existente. Essa ferramenta propaga as atribuições de ACL do contêiner raiz para todos os diretórios e arquivos subjacentes.

Remover permissões em excesso

Depois de aplicar as ACLs recursivamente, verifique as permissões para cada diretório e arquivo.

Remova quaisquer conjuntos Group ou User que não devem ter acesso a diretórios ou arquivos específicos. Por exemplo, remova User2 da pasta Portland/, e para a pasta Idaho, remova Group2 e User2 de suas atribuições, e assim por diante.

Estrutura de atribuições de ACL de exemplo

Aqui está um diagrama da estrutura de atribuição de ACL para a hierarquia de diretório fictícia na documentação do ADLS Gen2.

Atualizar atribuições de ACL ao longo do tempo

Ao longo do tempo, à medida que novas atribuições de ACL são adicionadas ou modificadas, repita as etapas acima para garantir o alinhamento adequado de propagação e permissões. As permissões atualizadas no ADLS Gen2 são atualizadas no índice de pesquisa quando você ingerir novamente o conteúdo usando o indexador.

Configurar a Pesquisa de IA do Azure

Lembre-se de que o serviço de pesquisa deve ter:

• Acesso habilitado por função
• Identidade gerenciada configurada

Authorization

Para a execução do indexador, o cliente que emite a chamada à API deve ter permissão de Colaborador do Serviço de Pesquisa para criar objetos, permissão de Colaborador de Dados de Índice de Pesquisa para executar importação de dados e Leitor de Dados de Índice de Pesquisa para consultar um índice.

Se estiver testando localmente, você deverá ter as mesmas atribuições de função. Para obter mais informações, confira Conectar-se à Pesquisa de IA do Azure usando funções.

Configurar a indexação

No Azure AI Search, configure um indexador, uma fonte de dados e um índice para efetuar pull de metadados de permissão dos blobs do ADLS Gen2.

Criar a fonte de dados

Esta seção complementa os dados de índice do ADLS Gen2 com informações específicas para ingerir permissões junto com o conteúdo do documento em um índice do Azure AI Search.

• O tipo de fonte de dados deve ser adlsgen2.

• A fonte de dados deve ter indexerPermissionOptions com userIds, groupIds e/ou rbacScope.

  • PararbacScope, configure a cadeia de conexão no formato de identidade gerenciada.

  • Para cadeias de conexão que usam uma identidade gerenciada atribuída pelo usuário, você também deve especificar a identity propriedade.

Exemplo de JSON com identidade gerenciada pelo sistema:

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

Exemplo de esquema JSON com uma identidade gerenciada pelo usuário na cadeia de conexão:

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

Criar campos de permissão no índice

No Azure AI Search, verifique se o índice contém definições de campo para os metadados de permissão. Os metadados de permissão podem ser indexados quando indexerPermissionOptions é especificado na definição da fonte de dados.

Atributos de esquema recomendados para ACL (UserIds, GroupIds) e Escopo do RBAC:

• Campo de IDs de usuário com valor userIds permissionFilter.
• IDs de grupo preenchidos com valor permissionFilter groupIds.
• Campo de escopo RBAC com valor permissionFilter rbacScope.
• Propriedade permissionFilterOption para habilitar a filtragem no momento da consulta.
• Usar campos de string para metadados de permissão
• Definido filterable como true em todos os campos.

Observe que retrievable é falso. Você pode defini-lo como verdadeiro durante o desenvolvimento para verificar se as permissões estão presentes, mas lembre-se de voltar a false antes de implantar em um ambiente de produção.

Exemplo de esquema JSON:

{
  ...
  "fields": [
    ...
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

Configurar o indexador

Os mapeamentos de campo em um indexador determinam o caminho dos dados para os campos em um índice. Campos de alvo e destino que variam por nome ou tipo de dados exigem um mapeamento de campo explícito. Os seguintes campos de metadados no ADLS Gen2 poderão precisar de mapeamentos de campo se você variar o nome do campo:

• metadata_user_ids (Collection(Edm.String)) – a lista de IDs de usuário da ACL.
• metadata_group_ids (Collection(Edm.String)) – a lista de IDs do grupo ACL.
• metadata_rbac_scope (Edm.String) – o escopo RBAC do contêiner.

Especifique fieldMappings no indexador para rotear os metadados de permissão para os campos de destino durante a indexação.

Exemplo de esquema JSON:

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

Recomendações e práticas recomendadas

• Planeje cuidadosamente a estrutura de pastas do ADLS Gen2 antes de criar pastas.

• Organize identidades em grupos e use grupos sempre que possível, em vez de conceder acesso diretamente a usuários individuais. Adicionar continuamente usuários individuais em vez de aplicar grupos aumenta o número de entradas de controle de acesso que devem ser controladas e avaliadas. Não seguir essa prática recomendada pode levar a atualizações de metadados de segurança mais frequentes necessárias para o índice à medida que esses metadados são alterados, causando atrasos e ineficiências maiores no processo de atualização.

Sincronizar permissões entre conteúdo indexado e de origem

Habilitar o enriquecimento de ACL ou RBAC em um indexador funciona automaticamente apenas em duas situações:

• A primeira execução completa do indexador/rastreamento de dados: todos os metadados de permissão que existem nesse momento para cada documento são capturados.

• Documentos novos adicionados após a habilitação do suporte a ACL/RBAC: suas informações de ACL/RBAC são ingeridas junto com o conteúdo.

Qualquer alteração de permissão feita após um documento já ter sido indexado (por exemplo, adicionar um usuário a uma ACL ou alterar uma atribuição de função) não aparecerá no índice de pesquisa, a menos que você aponte explicitamente o indexador para rastrear os metadados de permissão do documento novamente.

Escolha um dos seguintes mecanismos, dependendo de quantos itens foram alterados:

Exemplo de API resetdocs (versão prévia):

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2025-08-01-preview 
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

Exemplo de API ressincronização (versão prévia):

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2025-08-01-preview 
{ 
  "options": [ 
    "permissions" 
  ] 
} 

Acompanhamento de exclusão

Para gerenciar efetivamente a exclusão de blobs, verifique se o acompanhamento de exclusão está habilitado antes que o indexador seja executado pela primeira vez. Esse recurso permite que o sistema detecte blobs excluídos de sua origem e os exclua do índice.

Consulte também

• Conectar à Pesquisa de IA do Azure usando funções
• Query-Time Aplicação de ACL e RBAC
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API