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

** Azure Data Lake Storage (ADLS) Gen2 dá suporte ao acesso por usuário a diretórios e arquivos por meio de listas de controle de acesso (ACLs) e controle de acesso baseado em funções (Azure RBAC). Não há suporte para o controle de acesso baseado em Attribute (Azure ABAC).

Pesquisa de IA do Azure  pode ingerir esses metadados de permissão (versão prévia) juntamente com o conteúdo do documento usando uma API REST de visualização. Os usuários que não têm acesso a um diretório ou arquivo no armazenamento não veem os documentos correspondentes nos resultados da pesquisa. Essa é uma das várias estratégias para document-level access control em Pesquisa de IA do Azure .

Este artigo explica como configurar um indexador ADLS Gen2 ou uma fonte de dados de blob ADLS Gen2 para importar automaticamente metadados de permissão em um índice de pesquisa. Ele complementa os dados de índice do ADLS Gen2 e cria uma fonte de conhecimento de blobs para o ADLS Gen2 com informações específicas sobre a ingestão de permissões. Para enviar metadados de permissão manualmente, consulte Como usar a API de push para indexar ACLs de documentos.

diagrama

Pré-requisitos

• Autenticação e autorização de 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 usem Microsoft Entra ID. As atribuições de função são usadas para cada conexão autenticada.

• Pesquisa de IA do Azure em uma camada faturável (Básica ou superior) em qualquer região. O serviço de pesquisa deve ter acesso baseado em função habilitado e uma identidade gerenciada atribuída por usuário ou sistema.

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

• API REST versão 2025-05-01-preview ou posterior para ingestão de permissões do indexador. API REST versão 2025-11-01-preview ou posterior para oferecer suporte a fontes de conhecimento. Use a API REST de versão prévia mais recente ou um pacote de versão prévia do SDK que dá suporte a filtros de permissão.

Limitações

• O portal Azure não dá suporte a esse recurso.

• Os limites do ADLS Gen2 em atribuições de função e entradas ACL se aplicam.

• As owning users, owning groups e Other (all) categorias de identidade de ACL não têm suporte durante a visualização. Use as atribuições named users e named groups em vez disso.

• 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ê usar qualquer um desses recursos em um conjunto de habilidades ou indexador, as permissões no nível do documento não serão incluídas no conteúdo indexado.

  • Habilidade de API Web personalizada

  • Repositório de conhecimento, incluindo o repositório de ativos necessário para fornecimento de imagens (versão preliminar) na recuperação por meio de agentes. Portanto, a veiculação de imagens não é compatível com fontes de conhecimento que fazem ingestão de ACLs ou escopos de RBAC.

  • Cache de enriquecimento do indexador

  • Sessões de depuração

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 Pesquisa de IA do Azure . Explica quais mecanismos de controle de acesso do Azure Data Lake Storage (ADLS) Gen2 a Pesquisa de IA dá suporte ou mapeia. Isso ajuda você a entender como as permissões são impostas no nível do documento.

No momento da consulta, Pesquisa de IA do Azure  avalia primeiro o RBAC no nível do contêiner e verifica as entradas de ACL no nível do documento. O acesso é concedido se algum mecanismo o permitir.

Sobre permissões hierárquicas de ACL

Indexadores e fontes de conhecimento 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 ou fonte de conhecimento coleta ACLs de cada container e diretório. Em seguida, ele determina o acesso efetivo em níveis mais baixos e continua até resolver permissões 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 o ADLS Gen2

Um indexador ou fonte de conhecimento 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.

Autorização

Para indexação, a identidade do serviço de pesquisa deve ter a permissão Leitor de Dados do Blob de Armazenamento.

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 para 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 ACLs recursivamente, revise 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 na pasta Portland/, e para a pasta Idaho, remova Group2 e User2 de suas atribuições, e assim por diante.

Exemplo de estrutura de atribuições de ACL

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.

Atualizações das 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 anteriores 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 ou a fonte de conhecimento.

Configurar Pesquisa de IA do Azure 

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

• Acesso baseado em função habilitado
• Identidade gerenciada configurada

Autorização

Para indexação, 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, consulte Conectar-se ao Pesquisa de IA do Azure  usando roles.

Configurar uma fonte de conhecimento

Se você estiver usando uma fonte de conhecimento, as definições na fonte de conhecimento serão usadas para gerar um pipeline de indexação completo (indexador, fonte de dados e índice). As atribuições de ACL são detectadas e incluídas automaticamente no índice gerado. Não é necessário modificar nenhum dos objetos gerados se você quiser a herança de permissões no conteúdo indexado.

Principais pontos sobre a configuração que o fazem funcionar para este cenário:

• isADLSGen2 é definido como true, atendendo ao requisito da fonte de dados para esse cenário.
• ingestionPermissionOptions especifica IDs de usuário e grupo.

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

Configurar indexação baseada em indexador

Se você estiver usando um indexador, configure-o, juntamente com a fonte de dados e o índice, para extrair metadados de permissão dos blobs do Azure Data Lake Storage Gen2.

Criar a fonte de dados

Esta seção complementa os Dados de índice do ADLS Gen2 com informações específicas para importar permissões, além do conteúdo do documento, em um índice da Pesquisa de IA do Azure.

• O tipo de fonte de dados deve ser adlsgen2.

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

  • Para rbacScope, 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 no 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

Em Pesquisa de IA do Azure , 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 identificador de usuário (ID) com o valor permissionFilter userIds.
• Campo IDs de grupo com valor de permissionFilter groupIds.
• Campo de escopo RBAC com valor de permissionFilter rbacScope.
• Propriedade permissionFilterOption para habilitar a filtragem no momento da consulta.
• Usar campos de texto 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 definem o caminho de dados para os campos em um índice. Campos de destino e alvo 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 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 depois que o suporte a ACL/RBAC foi adicionado: suas informações de ACL/RBAC são ingeridas junto com o conteúdo.

Se você alterar permissões de documento, como adicionar um usuário a uma ACL ou atualizar uma atribuição de função, a alteração não aparecerá no índice de pesquisa, a menos que você diga ao 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=2026-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=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
} 

Acompanhamento de exclusão

Para gerenciar a exclusão de blobs de forma eficaz, certifique-se de que o rastreamento de exclusão esteja habilitado antes que o indexador seja executado pela primeira vez. Esse recurso permite que o sistema detecte blobs excluídos em sua origem e os remova do índice.

Conteúdo relacionado

• Conectar a Pesquisa de IA do Azure  usando perfis de acesso
• Aplicação de ACL e RBAC em Tempo de Consulta
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API