Como as permissões de negócio são declaradas, sincronizadas e aplicadas — do código Spring Boot ao gating da interface Next.js.
Destinatários: developers que precisam de proteger funcionalidades de negócio — no backend (API Spring Boot), no frontend (aplicação Next.js), ou em ambos.
O iGRP tem um único modelo de permissões partilhado por toda a plataforma. O Access Management é a fonte de verdade; o teu código declara as permissões que existem, e o JWT transporta as que foram concedidas ao utilizador.
Esta secção divide-se em dois guias, um por cada lado da stack:
| Guia | O que cobre |
|---|---|
| Backend — Spring Boot | Declarar permissões com @IgrpPermission, sincronizar com o Access Management, proteger endpoints com @PreAuthorize. |
| Frontend — Next.js | Proteger páginas, componentes e server actions a partir das claims do token. |
O ciclo de vida completo
Só a anotação é escrita à mão: o registo e a sincronização são automáticos. A concessão é uma decisão do administrador no Access Management, e os gates correm a cada pedido.
O ponto essencial
Só declaras permissões num lugar: o código Java do backend. O frontend consome os mesmos códigos de permissão pelas claims do token — não os redeclara.
Camadas de aplicação
Nem todas as verificações têm a mesma força. Esta tabela é a que mais interessa perceber antes de escrever qualquer gate:
| Âmbito | Mecanismo | Força |
|---|---|---|
| Componente (frontend) | <IGRPAuthorization> / usePermissions() | Cosmético — mostra/esconde UI |
| Menu | Scoping server-side do Access Management | Navegação de confiança |
| Página (frontend) | igrpAssertAuthorize() → forbidden() | Gate de render aplicado |
| Server action (frontend) | igrpAuthorize() + API do Access Management | Aplicação real |
| Endpoint (backend) | @PreAuthorize + IgrpAuthorizationService | Aplicação real |
Um botão escondido não é segurança
Esconder um botão no frontend impede o utilizador de o ver, não de invocar a operação. Um controlo protegido com uma server action desprotegida atrás não é seguro. A aplicação real vive no backend e na API do Access Management.
Anatomia do JWT
Ambos os lados leem o mesmo token. As claims relevantes:
{
"sub": "…", // id interno do utilizador (String, não garantidamente UUID)
"org": "DEPT_IGRP", // departamento ativo
"selectedRole": "DEPT_IGRP.superadmin", // perfil ATIVO (não a união de todos)
"is_super_admin": true, // contorna todas as verificações
"permissions": ["DEPT_IGRP.manage_access"] // permissões concedidas, `${dept}.${sufixo}`
}Duas consequências que causam confusão com frequência:
selectedRole é singular. Só o perfil atualmente selecionado é exposto como ROLE_<code>, não todos os perfis atribuídos ao utilizador. hasRole('X') avalia contra um perfil de cada vez — o que o utilizador escolheu no login. Sempre que possível, desenha as verificações contra permissões, não perfis: são mais finas e sobrevivem a renomeações e reorganizações.
is_super_admin contorna tudo. Quando é true, todas as verificações de permissão passam — nos dois lados. Ver backend §8.3 para o detalhe e para saber como excluir um endpoint específico desse bypass.
Nomenclatura das permissões
O código canónico é uma string pontuada em minúsculas, com namespace do teu contexto de negócio:
my.invoice.create
hr.employee.viewNo backend declaras o código completo. No frontend passas normalmente apenas o sufixo ("manage_access"), que é auto-qualificado com o departamento ativo (org) do token. Um nome sem ponto e sem org no token é negado — fail-closed.
Latência de revogação
Os gates leem claims de um token já emitido. Uma revogação no Access Management não tem efeito imediato:
- Backend: o
@PreAuthorizecontinua a passar até o utilizador obter um novo JWT. - Frontend: idem, até o token refrescar (TTL curto) ou novo login.
Para uma operação que tem de trancar no instante em que o acesso é retirado, a verificação tem de ser feita contra a API do Access Management, que está sempre fresca.
Por onde começar
- Vais construir uma API de negócio que define as suas próprias permissões? → Backend — Spring Boot
- Vais proteger páginas e componentes numa aplicação Next.js? → Frontend — Next.js
- Queres entender como o Access Management gere recursos, perfis e menus? → Access Manager
Última atualização: