JWT no Spring Security com Spring Boot: autenticação moderna passo a passo

JWT virou padrão de fato em muitas APIs Spring Boot porque encaixa bem em cenários sem sessão no servidor, integra com front-ends separados e facilita escalar autenticação sem depender de estado compartilhado. O problema é que muita implementação funciona “até o primeiro bug de segurança” ou até o time precisar manter aquilo por mais de algumas semanas. Se voce quiser comparar essa abordagem com outro cenario comum no ecossistema Spring, vale revisar JWT Spring Boot Java: Guia Completo com Exemplo Prático.

A proposta aqui é montar uma autenticação moderna com Spring Security, usando filtro para validar o token, configuração explícita da cadeia de segurança e endpoints protegidos com clareza. Se você ainda está entendendo o contexto do ecossistema, vale revisar também O que é o Spring Boot e para que serve?, porque ele ajuda a situar melhor a arquitetura. Para complementar esse ponto com um exemplo proximo do dia a dia, consulte O que é o Spring Boot e para que serve?.

Como a autenticação JWT encaixa no Spring Security

No fluxo mais comum, o usuário envia login e senha para um endpoint público. Se a credencial estiver correta, a aplicação gera um token assinado com validade curta e devolve esse JWT ao cliente. A partir daí, cada requisição protegida carrega o token no cabeçalho Authorization, e o Spring Security usa esse valor para montar o contexto de autenticação. Esse detalhe conversa bem com o que eu mostrei em O erro de segurança que quase todo backend Java comete com JWT.

O ponto central é este: com JWT, o servidor não precisa guardar sessão para cada usuário. Isso simplifica o desenho da API, mas exige disciplina no controle de expiração, assinatura e tratamento de autorização. Um JWT não substitui uma estratégia de segurança bem feita; ele só troca o mecanismo de estado. Se quiser aprofundar o assunto por outro angulo, leia tambem Controller vs RestController no Spring Boot: Qual usar em APIs REST?.

Quando usar JWT e quando evitar

JWT faz sentido quando a API atende aplicações web, mobile ou múltiplos consumidores e você quer autenticação stateless. Ele também ajuda quando o front-end está separado do back-end e a troca de credenciais precisa ser simples. Em compensação, se o seu sistema depende muito de revogação imediata de acesso, controle fino de sessão ou logout obrigatório em tempo real, o desenho com JWT precisa ser complementado com estratégia de blacklist, refresh token ou armazenamento de sessão. Quando esse tipo de duvida aparece em projeto real, eu costumo voltar neste material: Status HTTP em API REST com Spring Boot: Guia Completo.

Estrutura básica do projeto

Uma implementação limpa costuma separar responsabilidade em camadas bem definidas. O controller recebe o login, um serviço valida credenciais e gera o token, outro componente faz a validação do JWT nas requisições seguintes, e a configuração do Spring Security define quais rotas são públicas e quais exigem autenticação.

Esse desenho combina muito bem com APIs REST. Se você ainda tem dúvidas sobre a diferença entre estilos de controller no ecossistema Spring, vale conferir Controller vs RestController no Spring Boot: Qual usar em APIs REST?, porque a escolha impacta diretamente como o endpoint de autenticação devolve JSON.

Dependências mais comuns

Em um projeto Spring Boot moderno, normalmente você vai usar spring-boot-starter-web, spring-boot-starter-security e uma biblioteca de JWT para assinatura e parsing do token. Também vale considerar spring-boot-starter-validation para validar payloads de login e evitar entrada malformada desde a borda da aplicação.

Na prática, não há ganho em complicar a pilha logo no início. O suficiente para produzir login, validar token e proteger rotas já resolve boa parte dos cenários reais.

Configurando o Spring Security sem a abordagem antiga

Em versões mais recentes do Spring Security, a configuração moderna evita herdar classes antigas e privilegia beans explícitos. O resultado fica mais legível e menos acoplado ao comportamento legado da framework.

Uma configuração típica define o SecurityFilterChain, desabilita CSRF quando a API é stateless, libera endpoints públicos como autenticação e documentação interna, e exige autenticação para o restante. A ordem importa bastante, porque o filtro JWT precisa ser executado antes da decisão final de acesso.

Exemplo de configuração central

O desenho costuma seguir esta lógica: criar um bean SecurityFilterChain, registrar um AuthenticationProvider se você for autenticar usuário e senha com UserDetailsService, e adicionar um filtro customizado antes do UsernamePasswordAuthenticationFilter. Esse filtro vai inspecionar o cabeçalho Authorization, extrair o token e tentar construir o Authentication no SecurityContext.

Quando a API é stateless, também faz sentido desativar sessão de forma explícita. Assim o Spring Security não tenta criar estado desnecessário e você evita comportamentos confusos em ambientes com múltiplas instâncias.

Gerando o JWT no login

O endpoint de login recebe credenciais e, se estiverem corretas, devolve o JWT. O payload do token normalmente carrega identificador do usuário, papel ou autoridade principal e timestamps de emissão e expiração. Quanto menor o payload, melhor. Colocar dados demais no token só aumenta acoplamento e risco de vazamento de informação.

Uma boa prática é evitar colocar informações sensíveis no JWT, porque token não é criptografia; ele é apenas assinado. Qualquer cliente consegue ler o conteúdo. Esse tipo de detalhe é justamente o que costuma gerar erro de produção, e por isso vale muito a leitura de O erro de segurança que quase todo backend Java comete com JWT.

Tempo de vida e expiração

Token de acesso deve ter expiração curta. Isso reduz janela de abuso caso o token seja capturado. Em sistemas mais maduros, o acesso é renovado com refresh token, que pode ter uma política diferente de expiração e revogação. Mesmo que você não implemente refresh token no primeiro momento, deixar a expiração bem definida já é um avanço importante.

Validando o token com um filtro customizado

O coração da autenticação JWT no Spring Security costuma ser um filtro que roda em todas as requisições. Ele lê o cabeçalho Authorization, verifica se o valor começa com Bearer, extrai o JWT, valida assinatura e prazo, e só então cria o contexto autenticado.

Se o token estiver ausente ou inválido, o filtro não deve “inventar” autenticação. O mais correto é seguir o fluxo padrão da cadeia de segurança e permitir que o Spring responda com 401 quando a rota exigir acesso autenticado.

Fluxo prático do filtro

Primeiro, você identifica se existe token no header. Depois valida assinatura e expiração. Se estiver tudo certo, carrega os dados do usuário, monta uma Authentication com authorities apropriadas e salva isso no SecurityContextHolder. A partir daí, o restante da cadeia entende que a requisição já está autenticada.

Esse passo é o que dá consistência ao sistema. Sem ele, você até gera token, mas não consegue transformar o JWT em autorização real dentro do Spring Security.

Protegendo endpoints com roles e autenticação

Depois que o token está funcionando, o próximo passo é restringir rotas. Alguns endpoints ficam públicos, como login e talvez cadastro inicial. Outros exigem autenticação simples. E há casos em que a aplicação precisa distinguir perfil de admin, operador ou usuário comum.

O Spring Security permite isso de forma declarativa, seja com configuração por rota ou com anotações em métodos. Em APIs REST, a combinação de configuração central e regras pontuais costuma ficar mais fácil de manter, especialmente quando o projeto cresce.

Respostas corretas para acesso negado

Uma API bem comportada precisa diferenciar bem os cenários. Sem token válido, o mais adequado é retornar 401 Unauthorized. Com token válido, mas sem permissão suficiente, o correto é 403 Forbidden. Isso ajuda o cliente a entender o que aconteceu sem adivinhar.

Se você quer aprofundar esse ponto, vale ler Status HTTP em API REST com Spring Boot: Guia Completo, porque a escolha do status influencia muito a clareza da sua autenticação e da sua autorização.

Boas práticas que evitam dor de cabeça

JWT resolve muita coisa, mas algumas práticas fazem diferença real no dia a dia. Use expiração curta, mantenha segredo de assinatura fora do código, registre logs sem vazar token completo e trate falha de validação de forma previsível. Em produção, um detalhe simples como logar o conteúdo inteiro do Authorization pode virar incidente.

Também vale evitar colocar o JWT em local inseguro no front-end, revisar renovação de token e separar claramente autenticação de autorização. Em projetos maiores, confundir essas responsabilidades gera código difícil de evoluir e buracos de segurança desnecessários.

Quando a implementação precisa de uma base mais completa com geração e validação, o conteúdo JWT Spring Boot Java: Guia Completo com Exemplo Prático complementa bem a parte de biblioteca e estrutura do token. Aqui o foco é a integração com o Spring Security e a proteção real das rotas.

Autorização por perfil e proteção por rota

Depois que o token foi validado, o passo seguinte e decidir o que cada usuario autenticado realmente pode fazer. Em projeto real, a maior confusao aparece quando autenticacao e autorizacao sao tratadas como se fossem a mesma coisa. Nao sao. O JWT prova quem fez login; as regras de acesso definem se aquele usuario pode chegar em cada rota.

No Spring Security, a abordagem mais previsivel costuma ser combinar regras por rota com roles ou authorities claras. Endpoints publicos como login ficam liberados, endpoints autenticados exigem token valido e rotas mais sensiveis usam perfil explicito, como ADMIN ou OPERADOR. Isso reduz a chance de controller solto decidir seguranca por conta propria.

Quando consultar permissao no token e quando consultar o sistema

Colocar roles no token funciona bem quando essas permissoes mudam pouco e a API precisa responder rapido. Quando acesso muda o tempo todo, confiar so no JWT pode atrasar a revogacao ate a expiracao. Nesses cenarios, uma abordagem hibrida costuma ser mais honesta: o token carrega identidade e perfil principal, enquanto validacoes criticas consultam banco ou cache.

Boas decisoes para producao

JWT so continua simples em producao quando a implementacao evita atalhos. Use expiracao curta, segredo fora do codigo, resposta HTTP coerente e um filtro que autentica sem invadir regra de negocio. Quando o token esta ausente ou invalido, o natural e retornar 401. Quando o usuario esta autenticado, mas sem permissao suficiente, o correto e 403.

Tambem vale revisar revogacao, refresh token e observabilidade. Nem todo projeto precisa disso no primeiro dia, mas ignorar completamente esse assunto costuma cobrar caro quando a API cresce. Se voce quiser entrar mais fundo na parte de organizacao das rotas e do fluxo protegido, use como complemento Como proteger APIs REST com Spring Security: autorizacao, filtro JWT e fluxo stateless.

Conclusão

JWT com Spring Security funciona bem quando a solução é pensada como autenticação stateless de verdade, não como uma sessão disfarçada. O valor está no fluxo completo: login consistente, token bem assinado, filtro enxuto, configuração clara e respostas HTTP corretas para cada cenário.

Se o projeto começar simples e seguir essas decisões desde o início, a API fica mais previsível, mais fácil de testar e bem mais segura para evoluir. A diferença entre um JWT que só “passa no Postman” e uma autenticação sólida está exatamente nesses detalhes de arquitetura e implementação.

FAQ

JWT substitui senha?

Não. A senha é usada para autenticar o usuário no login. O JWT entra depois, como prova assinada de que aquela autenticação já aconteceu.

Preciso de sessão no servidor para usar JWT?

Não necessariamente. O desenho mais comum com JWT em Spring Security é stateless, sem armazenar sessão por usuário no servidor.

Posso colocar dados sensíveis dentro do token?

Não é uma boa ideia. JWT é assinado, não escondido. O conteúdo pode ser lido por qualquer cliente que tenha o token.

401 e 403 são a mesma coisa?

Não. 401 significa que a autenticação falhou ou não foi enviada. 403 significa que o usuário está autenticado, mas não tem permissão para acessar a rota.