Roles e Permissões — Controle de Acesso

Controlar quem pode ver e fazer o quê costuma virar uma planilha de permissões que ninguém mantém — e um incidente esperando para acontecer. No DATTA cada funcionalidade declara uma permissão nomeada, as permissões são agrupadas em roles administráveis pela interface, e tudo que não foi concedido é negado por padrão. Você enxerga o mapa de acessos em uma tela, ajusta com poucos cliques e ganha rastro de auditoria de cada negação.

Conceitos

• Permissão — uma capacidade nomeada e específica (ex.: CHAT_SEND, RULES_EDIT, PLATFORM_ADMIN). É a menor unidade de controle. O catálogo é central: toda permissão da plataforma vive nele, e criar permissão fora do catálogo é bug — ninguém consegue conceder o que não está lá.
• Role — um agrupamento administrável de permissões. Você atribui roles a usuários; a plataforma verifica permissões. Isso dá granularidade sem multiplicar o trabalho de gestão.
• Permissão sensível — permissões marcadas como sensíveis (revelar segredos, operações destrutivas) exigem motivo registrado em auditoria, limite de uso reforçado e confirmação dupla na interface.
• Negar por padrão — se o usuário não tem a permissão, a ação é bloqueada com mensagem amigável em português (HTTP 403) e a tentativa fica registrada na trilha de auditoria.

Perfis prontos (roles built-in)

A plataforma já vem com quatro perfis que cobrem a maioria das equipes:

Os perfis prontos são sincronizados na base de sistema a cada início da plataforma, de forma idempotente. Roles próprias, criadas por você, são preservadas nessa sincronização — nada que você criou é sobrescrito.

Onde se administra

O ponto de gestão é Sistema›Segurança›Roles e Permissões, onde o catálogo aparece agrupado por categoria — o mesmo agrupamento usado no resto da interface. Para conceder acesso a uma pessoa, use Sistema›Segurança›Usuários: cada usuário recebe uma role base e pode ganhar permissões diretas adicionais para casos pontuais. Detalhes do cadastro estão no guia de usuários.

Mudanças de permissão valem a partir do próximo login do usuário. O bloqueio no servidor, porém, é imediato: mesmo que uma tela antiga ainda mostre um botão, a ação é negada.

Categorias do catálogo

Cada permissão pertence a uma categoria. É esse agrupamento que organiza a tela de roles:

CHAT          GRAPH         DOCUMENT      RULES         PROCESSOS
USERS         CONFIG        MODELS        AUDIT         BACKUP
EMBEDDING     SEARCH        MASKING       CATALOG       ONTOLOGY
GLOSSARY      LINEAGE       PROFILING     PIPELINE      TWIN
JDBC          DRIVER        DISCOVERY     DATTAX        DATTABI
MCP           PROMPT        STATS         NOTEBOOK      SYSTEM
PLATFORM      NEO4J         OPENSEARCH    VALKEY        KAFKA
LLM           SIQL

Permissões transversais

Estas cobrem capacidades compartilhadas que muitas telas usam, e por isso se comportam de forma diferente das permissões funcionais finas:

Distribuição padrão por perfil

Recorte das permissões transversais e das mais usadas, e como os perfis prontos as distribuem. A lista completa está sempre visível na própria tela de roles — ela é a fonte atualizada, categoria por categoria.

Segurança em camadas

• A interface esconde o que o usuário não pode fazer — ninguém clica num botão só para receber um erro.
• A plataforma bloqueia no servidor, independentemente da interface. Essa é a barreira real: ela nunca depende do navegador.
• A auditoria registra toda negação com autor, permissão exigida, recurso e desfecho. Com a interface escondendo as ações, uma negação registrada passa a sinalizar de fato uma tentativa anômala.

Toda negação de acesso gera o evento AUTHZ.PERMISSION_DENIED, com actor, permission, resource, method e outcome=denied. O evento cobre os dois caminhos de negação: o bloqueio por rota — nesse caso a permissão vem como (path-gate) e o recurso é a própria rota — e o bloqueio pela permissão declarada no endpoint, em que a permissão exigida aparece pelo nome e o recurso identifica classe e método.

O evento é gravado como log estruturado (logger datta.audit.authz, nível WARN, prefixo AUDIT event=AUTHZ.PERMISSION_DENIED) e levado pela telemetria da plataforma ao índice otel-logs-* do OpenSearch, consultável no Trace Analytics e no console de auditoria (/configurar/audit?type=AUTHZ). A escolha pelo log estruturado é deliberada: a plataforma não expõe hoje um endpoint de ingestão de auditoria por HTTP, então qualquer publicação por esse caminho cairia em erro silencioso — é o log que de fato garante o rastro. Criar esse endpoint de ingestão, ou migrar os demais publicadores para o mesmo canal de log, é trabalho separado.

Exemplo prático — modo somente leitura nas Regras de Triagem

O controle de acesso não só bloqueia: ele adapta a interface. A tela Regras de Triagem (/regras_triagem) é o caso canônico.

Antes, a tela mostrava os botões de escrita para qualquer usuário autenticado. Quem não tinha permissão clicava, recebia o erro traduzido em um aviso vermelho e ficava sem entender por quê — falha de experiência e de feedback de permissão. Hoje a tela lê a permissão do usuário logado e se adapta: as ações de escrita somem, um selo Somente leitura aparece no cabeçalho ao lado da contagem de regras, e as regras abrem em modo de visualização. O usuário enxerga e busca todo o conteúdo, sem botões que levariam a uma negação.

O gatilho é a presença de RULES_EDIT (ou da role ADMIN) — não a presença de RULES_VIEW. Se a leitura da permissão falhar por qualquer motivo, o modo somente leitura é o estado assumido: negar por padrão.

O que muda na tela

O selo só aparece para usuário logado sem permissão de edição. A engrenagem de Manutenção (apagar todas as regras) é separada e exige ADMIN estrito — RULES_EDIT não basta.

Regras geradas por IA (bloco "Regras Automáticas") ficam travadas para todos, inclusive quem tem RULES_EDIT, até serem movidas para um bloco personalizado. Esse bloqueio é independente do modo somente leitura por permissão e se soma a ele: com qualquer um dos dois ativo, os campos não aceitam edição e a barra Salvar / Descartar nunca surge.

O que o servidor exige

Toda mutação de regra — criar, atualizar, mover, excluir, ativar/desativar, testar referências normativas e gerar com IA, inclusive cancelar a geração — exige RULES_EDIT ou ROLE_ADMIN. O bloqueio é por rota, na configuração de segurança do próprio serviço de regras; os caminhos exatos estão na referência de API.

A leitura das regras, hoje, exige apenas token válido: qualquer usuário autenticado lista as regras. RULES_VIEW existe no catálogo e governa a distribuição por role e a intenção de governança, mas ainda não é enforçada na leitura. Endurecer isso exigiria acrescentar um bloqueio por rota também nas leituras — trabalho em aberto.

Um detalhe importante para quem implementa: nos serviços reativos, a permissão declarada em classe não é interceptada em métodos que retornam Mono/Flux — é por isso que o bloqueio das mutações é feito por rota. Os nomes das permissões do usuário chegam ao servidor pelo token e viram authorities; ROLE_ADMIN nunca é barrado. Há ainda um canal servidor-a-servidor (cabeçalho X-Internal-Token, que concede ROLE_INTERNAL_SERVICE mais RULES_VIEW e RULES_EDIT) para que a triagem em lote — assíncrona, sem token de usuário — consiga ler as regras sem cair em 401.

Quem cai no modo somente leitura

Na prática: usuários READ_ONLY (têm RULES_VIEW, não têm RULES_EDIT) e qualquer role própria sem RULES_EDIT. ADMIN e ADVANCED_USER editam normalmente.

ANALISTA não tem RULES_VIEW na distribuição padrão, mas isso não esconde a tela: o item Regras do menu (seção "Processar") não é filtrado por permissão, e a leitura está liberada para todo token válido. Um ANALISTA que abra a tela a vê em modo somente leitura, por não ter RULES_EDIT. O RULES_VIEW ausente reflete a intenção de governança, que hoje não é aplicada nem no menu nem no servidor.

Passo a passo do usuário

1. Abra Regras de Triagem. Se você só tem permissão de visualização, o selo Somente leitura aparece ao lado da contagem de regras.
2. Navegue, filtre por bloco/status e busque por número, título ou texto normalmente — a leitura é livre.
3. Selecione uma regra: o painel de detalhe abre com os campos travados, sem os botões Salvar, Excluir ou Ativar/Desativar.
4. Para ganhar edição, peça ao administrador a permissão RULES_EDIT (ou uma role que a contenha, como ADVANCED_USER).

Passo a passo do administrador

• Para conceder edição: atribua RULES_EDIT ao usuário — por role ou como permissão direta — em Sistema›Segurança›Usuários. A mudança vale no próximo login da pessoa.
• Para deixar alguém só consultando: garanta RULES_VIEW sem RULES_EDIT. O perfil READ_ONLY já atende.
• A operação destrutiva "Apagar todas as regras" (engrenagem de Manutenção) permanece exclusiva de ADMIN estrito e exige motivo com no mínimo 10 caracteres, registrado em auditoria — independentemente de RULES_EDIT.

Limitações conhecidas

• A permissão é lida quando a tela monta; reduzir a permissão no meio da sessão não atualiza o selo em tempo real. O servidor, porém, já bloqueia qualquer mutação independentemente do estado da tela.
• A interface é dica visual; a barreira é o servidor. Mesmo que a tela exibisse as ações por engano, a mutação seria negada.

Como uma permissão nova entra no catálogo

1. Declarar a permissão no catálogo central, na categoria adequada, com descrição em pt-BR e a marcação de sensível. Se a categoria ainda não existe, criá-la na lista de categorias.
2. Distribuí-la nos perfis prontos apropriados — lembrando que ADMIN cobre tudo automaticamente.
3. Anotar o(s) endpoint(s) com @RequirePermission("NOVA_PERMISSAO").
4. Documentar nesta página quando a permissão for transversal.
5. Atualizar os testes que validam o catálogo, se houver.

A anotação na prática

Em método:

@GetMapping("/datasets")
@RequirePermission("CATALOG_VIEW")
public Flux<DatasetDto> listDatasets() { ... }

Em classe, cobrindo todos os métodos:

// declarada na classe do controlador — vale para todos os seus métodos
@RequirePermission("AUDIT_VIEW")

A anotação funciona nos dois níveis, e o método sobrescreve a classe — não acumula: cada método tem exatamente uma exigência. Permissões terminadas em _ADMIN/:ADMIN ou _VIEW/:VIEW são herdadas automaticamente por ROLE_ADMIN, o que evita listar cada uma na role. Alternativa equivalente: @PreAuthorize("hasAuthority('X')").

Onde o catálogo fica armazenado

O catálogo é materializado no banco de sistema datta a cada início da plataforma, de forma idempotente:

(:Role {name, description, builtIn, createdAt, updatedAt})
   -[:TEM_PERMISSAO]-> (:Permissao {name})
(:Usuario)-[:TEM_ROLE]->(:Role)
(:Usuario)-[:TEM_PERMISSAO_DIRETA]->(:Permissao)   // grants individuais

A fonte da verdade é o código; o grafo existe para alimentar a tela de roles e para guardar as roles próprias e os grants diretos.

A sincronização roda sequencialmente e é precedida por uma rotina de higiene: deduplica nós :Permissao pelo nome, remove nós sem nenhuma aresta (permissões que saíram do catálogo) e cria as restrições de unicidade de Permissao.name e Role.name.

Solução de problemas — entradas repetidas ou permissões legadas na tela de roles. Basta reiniciar o componente de autenticação: a higiene roda no início. Sem reimplantar, dá para rodar o script scripts/neo4j-permissoes-dedup.cypher — as instruções estão no cabeçalho do próprio arquivo. Histórico: até 2026-06-10 a sincronização era concorrente e sem restrição de unicidade, e a criação simultânea gerava até 4 cópias por nome; o rebrand SPAT→DATTA deixou 24 entradas órfãs.

Cobertura atual (2026-05-09)

Uma varredura arquitetural em 2026-05-09 garantiu que 209 de 209 controladores REST tenham a permissão declarada, em classe ou em método. Os 10 endpoints intencionalmente sem controle de acesso são:

Os dois interceptadores de permissão — um para os serviços reativos, outro para os tradicionais — suportam:

• Anotação em classe, cobrindo todos os métodos sem repetição.
• Sobrescrita por método, quando um método precisa de permissão mais alta que a da classe. Exemplo: a área de busca exige SEARCH_EXECUTE na classe inteira, mas a exclusão de documentos por consulta exige SEARCH_INDEX_DELETE.
• Herança por ROLE_ADMIN das permissões terminadas em _ADMIN/:ADMIN ou _VIEW/:VIEW.

Anti-patterns rejeitados em revisão

• Endpoint sem permissão declarada.
• Permissão declarada com um nome que não existe no catálogo — impossível de conceder, então sempre nega.
• Checagem de role fixa no código (hasRole('ADMIN')) em vez da permissão específica, perdendo granularidade.
• Permissão garantida só na interface (esconder o botão) sem bloqueio no servidor.
• Permissão sensível sem evento de auditoria ou sem limite de uso.

Veja também: Usuários · Visão geral da API · Referência de API