Como proteger endpoints Spring Boot usando annotations

Spring Security oferece @PreAuthorize, mas em produtos multi-tenant com dezenas de permissions o código vira strings mágicas duplicadas. Annotations de domínio — ligadas ao seu IAM — deixam a intenção explícita no endpoint e centralizam a lógica de validação em um interceptor ou filter.

Abordagem declarativa

@RestController
@RequestMapping("/api/orders")
public class OrderController {

  @GetMapping("/{id}")
  @GatekeeperProtected(permissions = "orders:read")
  public Order get(@PathVariable UUID id) {
    return orderService.find(id);
  }

  @DeleteMapping("/{id}")
  @GatekeeperProtected(permissions = "orders:delete")
  public void delete(@PathVariable UUID id) {
    orderService.delete(id);
  }
}

O aspecto ou filter da SDK roda antes do método: valida JWT, extrai permissions do token, compara com a annotation e retorna 403 se faltar permissão — ou 401 se o token for inválido.

Quando usar annotations

• APIs REST com ações mapeáveis a permissions
• Times que querem ver regras de acesso no mesmo arquivo do endpoint
• Produtos que já usam IAM externo (Gatekeeper, Keycloak, etc.)

Erros comuns

• Annotation só no controller, esquecendo endpoints em @RestControllerAdvice ou WebFlux
• Permissão genérica demais — um único ADMIN bypass
• Não testar cenário 401/403 em integração
• Misturar lógica de tenant com lógica de permission no mesmo if

Como o Gatekeeper ID ajuda

A SDK Spring Boot do Gatekeeper fornece @GatekeeperProtected integrada ao fluxo de validação JWT e ao tenant configurado em YAML. Permissions vêm do Console — alterações não exigem redeploy.

Fundamentos de RBAC: RBAC em aplicações Java. Guia rápido na documentação da SDK.

Conclusão

Annotations não substituem um IAM sólido — mas eliminam ifs repetidos e documentam acesso no ponto certo. Em Spring Boot, é um dos caminhos mais legíveis para escalar autorização.