Controle de Acesso por Documento nas Knowledge Bases do Amazon Quick com S3

O problema: IA generativa e documentos sensíveis não combinam sem controle granular

Muitas organizações estão adotando ferramentas de busca e chat com IA para que equipes encontrem respostas rapidamente em grandes repositórios de documentos. O desafio é que nem todo documento pode ser acessado por qualquer pessoa — contratos jurídicos, relatórios financeiros e dados de RH exigem restrições específicas por usuário ou grupo.

Permissões grosseiras que controlam o acesso no nível da knowledge base inteira funcionam para cenários simples, mas não são suficientes quando a necessidade é restringir documentos ou pastas específicas a times, indivíduos ou sistemas autorizados. Para resolver isso, a AWS anunciou suporte a Listas de Controle de Acesso (ACL) no nível de documento para knowledge bases do Amazon Quick integradas ao Amazon Simple Storage Service (S3).

Com esse recurso, quando um usuário faz uma pergunta no chat, o Quick avalia a identidade desse usuário em relação à configuração de ACL e retorna apenas o conteúdo que ele está autorizado a visualizar.

Como funciona o controle de acesso por ACL no Amazon Quick

O recurso de ACL do S3 no Amazon Quick permite anexar permissões de acesso diretamente aos documentos. As permissões são definidas com políticas padrão de ALLOW (permitir) e DENY (negar) para usuários individuais ou grupos, e o Quick aplica essas regras no momento da consulta.

Há dois métodos de configuração de ACL, cada um adequado a diferentes necessidades operacionais:

Arquivo de ACL global (por exemplo, acl.json) — Um único arquivo centralizado que define permissões de acesso no nível de pasta (prefixo S3). Indicado para organizações com estruturas de permissão estáveis baseadas em pastas.
Arquivos de metadados por documento — Arquivos individuais de metadados ao lado de cada documento, contendo as entradas de controle de acesso específicas. Indicado quando as permissões mudam com frequência, pois apenas os documentos afetados precisam ser reindexados, e não estruturas de pastas inteiras.

A escolha entre os dois métodos deve considerar a frequência de mudanças de permissão e o nível de granularidade necessário:

Arquivo de ACL global: granularidade no nível de pasta, um único arquivo para manter, mas uma mudança de permissão reindexará o prefixo inteiro afetado. Recomendado para estruturas de acesso estáveis.
Metadados por documento: granularidade no nível de documento individual, um arquivo de metadados por documento, e apenas os documentos alterados são reindexados. Recomendado para permissões que mudam com frequência.

Comportamento de negação por padrão

Um ponto crítico: ao habilitar ACLs em uma knowledge base do S3 no Quick, qualquer documento ou prefixo que não esteja explicitamente listado na configuração de ACL é negado por padrão. Esse comportamento é chamado de “fail closed” — o sistema nega o acesso quando nenhuma regra explícita existe.

Por exemplo, se o bucket S3 tiver três pastas (/financeiro/, /juridico/ e /politicas/) e o arquivo de ACL conceder acesso apenas a /financeiro/ e /politicas/, a pasta /juridico/ será automaticamente negada para todos, mesmo sem uma regra DENY explícita para ela. Esse modelo de negação implícita funciona da mesma forma que o IAM da AWS.

Além disso, se um usuário ou grupo tiver tanto uma entrada ALLOW quanto uma DENY para o mesmo documento ou prefixo, a regra DENY sempre tem precedência. Isso permite criar regras ALLOW amplas para um grupo e aplicar restrições pontuais com DENY para recursos específicos.

Pré-requisitos para configurar ACLs no Amazon Quick

Antes de começar, é necessário ter:

Uma conta AWS com o Amazon Quick habilitado. Caso ainda não tenha, consulte o guia de primeiros passos com o Amazon Quick.
Um bucket do Amazon S3 com os documentos que serão indexados.
Usuários provisionados no Quick com endereços de e-mail que correspondam às identidades nos arquivos de ACL. Veja detalhes em gerenciamento de acesso de usuários no Amazon Quick.
Acesso de administrador no Quick para configurar atribuições de políticas do IAM (Gerenciamento de Identidade e Acesso) e criação de knowledge bases.
Familiaridade com conceitos de IAM e sintaxe básica de JSON.
Uma knowledge base de teste ou não-produção para validar a configuração de ACL.

Atenção: habilitar ACLs é uma operação irreversível. Não é possível desativá-las depois de ativadas. Se precisar remover a funcionalidade de ACL, será necessário criar uma nova knowledge base sem ACLs. Por isso, a AWS recomenda validar a configuração em ambiente de teste antes de aplicar em produção.

Controlando quem pode criar knowledge bases com buckets S3 restritos

As ACLs por documento controlam quais documentos os usuários podem acessar dentro de uma knowledge base, mas não controlam quem pode criar knowledge bases. Essa distinção é importante: sem controles adicionais, um usuário do Quick poderia criar uma nova knowledge base sobre o mesmo bucket sem habilitar ACLs, contornando os controles de acesso configurados.

Para evitar isso, as atribuições de políticas do IAM no Quick permitem restringir quais buckets S3 usuários ou grupos específicos podem usar para criar knowledge bases.

Passo 1: Criar uma política de acesso ao S3 no IAM

Crie uma política do IAM no console do IAM especificando quais buckets S3 os usuários atribuídos podem acessar. O exemplo abaixo concede acesso a dois buckets específicos:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListAllMyBuckets",
      "Resource": "arn:aws:s3:::*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:ListBucketVersions",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::amzn-s3-demo-bucket1",
        "arn:aws:s3:::amzn-s3-demo-bucket2"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectVersion"
      ],
      "Resource": [
        "arn:aws:s3:::amzn-s3-demo-bucket1/*",
        "arn:aws:s3:::amzn-s3-demo-bucket2/*"
      ]
    }
  ]
}

Substitua amzn-s3-demo-bucket1 e amzn-s3-demo-bucket2 pelos nomes reais dos buckets S3 que devem ser liberados.

Passo 2: Atribuir a política no Quick

Após criar a política do IAM, ela deve ser atribuída a usuários ou grupos pelo console de administração do Quick, em Permissões > Atribuições de políticas IAM. Usuários que não tiverem acesso explícito concedido por uma atribuição de política do IAM não poderão usar os buckets restritos para criar knowledge bases — embora ainda possam acessar uma knowledge base compartilhada com eles. Para mais detalhes, consulte a documentação sobre restrição de acesso a buckets S3 com atribuições de políticas IAM.

Nota: políticas do IAM atribuídas pelo Quick têm precedência sobre políticas de nível de recurso AWS. Confirme que suas políticas do IAM atendem aos requisitos de acesso antes de atribuí-las.

Planejando a estrutura de controle de acesso

Antes de criar os arquivos de ACL, é necessário mapear as necessidades de acesso da organização: quais times, funções ou indivíduos precisam acessar quais conjuntos de documentos. Em seguida, escolha o método de ACL (global ou por documento) e alinhe as identidades — os nomes de usuário e grupo nos arquivos de ACL devem corresponder exatamente aos e-mails e nomes de grupo dos usuários no Quick (a correspondência de e-mail é insensível a maiúsculas, mas os nomes de grupo devem ser exatos). A associação de grupos é gerenciada no provedor de identidade (IdP), como o IAM Identity Center, e sincronizada com o Quick.

Opção 1: Configurar ACL com arquivo global

O arquivo de ACL global é um único arquivo JSON que mapeia prefixos S3 a entradas de controle de acesso. Ele deve ser carregado na raiz do bucket S3. O arquivo não precisa se chamar acl.json.

Cada entrada no array JSON especifica um prefixo S3 e suas entradas de controle de acesso associadas. Cada item em aclEntries inclui:

Name — O e-mail do usuário ou o nome do grupo. Deve corresponder exatamente à identidade no Quick.
Type — USER ou GROUP.
Access — ALLOW ou DENY.

Lembre-se: prefixos não listados no arquivo são negados por padrão. Após criar e carregar o arquivo no bucket, basta configurar a knowledge base no console do Quick apontando para o arquivo de ACL e iniciar uma sincronização. O Quick aplica as regras de ACL durante a indexação e apenas documentos com entradas ALLOW explícitas ficam disponíveis no chat.

Opção 2: Configurar ACL com arquivos de metadados por documento

Para controle por documento ou reindexação mais rápida quando as permissões mudam, é possível usar arquivos de metadados individuais. Cada documento no bucket S3 recebe um arquivo .metadata.json correspondente com as entradas de controle de acesso.

O arquivo de metadados inclui um array AccessControlList. Apenas esse campo é obrigatório para a aplicação das ACLs. Os demais campos (DocumentId, Attributes, Title, ContentType) são opcionais e servem para enriquecimento de metadados:

{
  "DocumentId": "finance-q3-report",
  "Attributes": {
    "_category": "financial-reports",
    "_created_at": "2025-10-01T00:00:00Z",
    "_source_uri": "s3://amzn-s3-demo-bucket/reports/q3-report.pdf"
  },
  "AccessControlList": [
    {
      "Name": "finance-team",
      "Type": "GROUP",
      "Access": "ALLOW"
    },
    {
      "Name": "contractor@example.com",
      "Type": "USER",
      "Access": "DENY"
    }
  ],
  "Title": "Q3 Financial Report",
  "ContentType": "PDF"
}

Para que a knowledge base encontre o arquivo de metadados correto, o sistema constrói o caminho S3 do arquivo de metadados adicionando o sufixo .metadata.json à chave S3 do documento. Por exemplo, se o arquivo for recipe.pdf, o arquivo de metadados esperado será recipe.pdf.metadata.json. Os arquivos de metadados podem ficar em um diretório dedicado (como s3://amzn-s3-demo-bucket/metadata) ou na mesma pasta do documento referenciado.

Documentos sem arquivo de metadados — ou com arquivo de metadados que não inclua um AccessControlList — são negados por padrão quando as ACLs estão habilitadas.

Verificando a configuração de ACL

Após a sincronização da knowledge base, é possível verificar se as ACLs estão funcionando corretamente pelo chat e pelos fluxos do Quick. No chat, basta conectar à knowledge base com ACL habilitada, desabilitar a busca web para isolar os resultados à knowledge base e testar perguntas sobre documentos com e sem permissão de acesso. O Quick não deve retornar conteúdo de documentos não autorizados para o usuário em questão.

O Amazon Quick também permite construir fluxos automatizados com consciência de ACL — pipelines que respeitam a governança de dados ao gerar resumos executivos, por exemplo, verificando quais documentos o usuário pode acessar antes de processá-los e, quando não há fontes internas acessíveis, realizando uma busca web como alternativa.

Atualizando as ACLs após a configuração inicial

O Quick não monitora os arquivos de ACL em tempo real. As permissões atualizadas entram em vigor na próxima sincronização da knowledge base, que ocorre diariamente por padrão. Para mudanças urgentes — como revogação de acesso — é recomendável acionar uma sincronização manual imediatamente após atualizar os arquivos de ACL no S3.

O escopo de reindexação depende do método escolhido: com o arquivo de ACL global, o prefixo inteiro afetado é reindexado; com metadados por documento, apenas os documentos cujos arquivos de metadados foram alterados são reindexados. Para organizações com mudanças frequentes de permissão, os arquivos de metadados por documento oferecem atualizações de acesso mais rápidas.

Segurança e auditoria dos arquivos de ACL

A AWS recomenda restringir as permissões s3:PutObject nos arquivos de ACL e metadados a um conjunto limitado de administradores. Qualquer pessoa que possa modificar esses arquivos pode conceder a si mesma acesso a qualquer documento — portanto, o acesso de escrita aos arquivos de ACL deve ser tratado como uma operação privilegiada.

Habilitar o versionamento S3 nos arquivos de ACL é uma boa prática para manter uma trilha de auditoria das mudanças de permissão. Todas as ações de criação e atualização de knowledge bases são registradas no AWS CloudTrail, incluindo se as ACLs estão habilitadas, o que fornece aos administradores uma trilha de auditoria de quem configurou as ACLs e quando. O Amazon Quick também oferece um recurso para monitorar o uso de armazenamento do índice, ajudando a rastrear o crescimento e detectar mudanças inesperadas no conteúdo indexado.

Limitações importantes

Antes de habilitar ACLs, é importante considerar:

ACLs não podem ser desabilitadas após ativadas. Se precisar remover a funcionalidade de ACL, será necessário criar uma nova knowledge base sem ACLs.
A correspondência de identidade do usuário é baseada em e-mail. O campo Name nas entradas de ACL deve corresponder exatamente ao endereço de e-mail associado à identidade do usuário no Quick. Se o e-mail de um usuário mudar, os arquivos de ACL devem ser atualizados e uma nova sincronização deve ser acionada.

Para limitações adicionais, consulte a documentação sobre limitações do conector de dados S3 e limitações de ACL de knowledge base no Amazon Quick.

Próximos passos

Para aprofundar o tema, a AWS disponibiliza a documentação do conector Amazon S3 com referência detalhada de configuração, e o guia de boas práticas de ACL com recomendações para estruturar controles de acesso em escala. Para conhecer mais sobre o Amazon Quick, acesse a página do produto, explore os recursos de segurança do Quick e participe da comunidade Quick para tirar dúvidas e compartilhar experiências.

Fonte

Restrict access to sensitive documents in your Amazon Quick knowledge bases for Amazon S3 (https://aws.amazon.com/blogs/machine-learning/restrict-access-to-sensitive-documents-in-your-amazon-quick-knowledge-bases-for-amazon-s3/)