I've read probably forty Spring Boot JWT tutorials over the years. They all show you the same thing: how to generate a token on login, how to validate it on each request, and how to wire up SecurityFilterChain. And they all stop right there.
What they skip is everything that matters in production: refresh token rotation, token revocation, and not sending tokens in JavaScript-readable headers when you don't have to. I've inherited two codebases where a "working JWT implementation" turned out to be a security hole you could drive a truck through. This article is the setup I now use by default.
What the typical tutorial gives you
The standard walkthrough produces something like this:
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http.csrf(AbstractHttpConfigurer::disable)
.sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.authorizeHttpRequests(auth -> auth
.requestMatchers("/auth/**").permitAll()
.anyRequest().authenticated())
.addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class);
return http.build();
}
This is fine. The filter reads the Authorization: Bearer <token> header, validates the signature, sets the SecurityContext. You can deploy this. The problem is what comes next.
The access token has an expiry — typically 15 to 60 minutes. What happens when it expires? In most tutorials: the user logs in again. In production: users complain, sessions die mid-work, and someone "fixes" it by setting expiry to 7 days. Now you have a long-lived token you can't revoke.
The right structure: short-lived access + rotating refresh
The pattern I use in every Spring Boot project now:
-
Access token: 15 minutes, stored in memory (JS variable or React state), never in
localStorage -
Refresh token: 7 days, stored in an
HttpOnly; Secure; SameSite=Strictcookie, not accessible to JavaScript - Rotation: every refresh request issues a new refresh token and invalidates the old one
- Revocation store: a small table (or Redis set) of invalidated refresh token IDs
Here's the refresh token entity:
@Entity
@Table(name = "refresh_tokens")
public class RefreshToken {
@Id
private String id; // UUID, stored in the cookie value
@ManyToOne(fetch = FetchType.LAZY)
private User user;
private Instant expiresAt;
private boolean revoked;
@CreationTimestamp
private Instant createdAt;
}
And the service that handles rotation:
@Service
@Transactional
public class RefreshTokenService {
private final RefreshTokenRepository repo;
private final Duration refreshExpiry = Duration.ofDays(7);
public RefreshToken create(User user) {
RefreshToken token = new RefreshToken();
token.setId(UUID.randomUUID().toString());
token.setUser(user);
token.setExpiresAt(Instant.now().plus(refreshExpiry));
token.setRevoked(false);
return repo.save(token);
}
public RefreshToken rotate(String oldTokenId) {
RefreshToken old = repo.findById(oldTokenId)
.orElseThrow(() -> new InvalidTokenException("Refresh token not found"));
if (old.isRevoked() || old.getExpiresAt().isBefore(Instant.now())) {
// Possible token reuse attack — revoke entire family
revokeAllForUser(old.getUser());
throw new InvalidTokenException("Refresh token expired or revoked");
}
old.setRevoked(true);
repo.save(old);
return create(old.getUser());
}
public void revokeAllForUser(User user) {
repo.revokeAllByUser(user);
}
}
The reuse detection is the part most tutorials omit entirely. If an attacker steals a refresh token and uses it, you now have two parties trying to use it. When the legitimate client tries to rotate and finds its token already consumed, you revoke everything and force a new login. This is the refresh token family pattern from the OAuth 2.0 Security Best Current Practice spec.
The cookie setup
The refresh token goes out in the response as a cookie, not in the JSON body:
@PostMapping("/auth/login")
public ResponseEntity<AccessTokenResponse> login(
@RequestBody LoginRequest req,
HttpServletResponse response) {
User user = authService.authenticate(req.email(), req.password());
String accessToken = jwtService.generateAccessToken(user);
RefreshToken refreshToken = refreshTokenService.create(user);
ResponseCookie cookie = ResponseCookie.from("refresh_token", refreshToken.getId())
.httpOnly(true)
.secure(true)
.sameSite("Strict")
.path("/auth/refresh")
.maxAge(Duration.ofDays(7))
.build();
response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
return ResponseEntity.ok(new AccessTokenResponse(accessToken));
}
Note .path("/auth/refresh") — the cookie is scoped to the refresh endpoint only. The browser won't send it on any other request. This reduces the attack surface on CSRF (though SameSite=Strict already handles most of that).
The refresh endpoint reads the cookie:
@PostMapping("/auth/refresh")
public ResponseEntity<AccessTokenResponse> refresh(
@CookieValue(name = "refresh_token", required = false) String refreshTokenId,
HttpServletResponse response) {
if (refreshTokenId == null) {
return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
}
RefreshToken newRefreshToken = refreshTokenService.rotate(refreshTokenId);
String newAccessToken = jwtService.generateAccessToken(newRefreshToken.getUser());
ResponseCookie cookie = ResponseCookie.from("refresh_token", newRefreshToken.getId())
.httpOnly(true)
.secure(true)
.sameSite("Strict")
.path("/auth/refresh")
.maxAge(Duration.ofDays(7))
.build();
response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
return ResponseEntity.ok(new AccessTokenResponse(newAccessToken));
}
The JWT service itself
Nothing exotic here, but I'll include it for completeness. I use io.jsonwebtoken:jjwt-api (JJWT 0.12.x) with Spring Boot 3:
@Service
public class JwtService {
@Value("${app.jwt.secret}")
private String secret;
private static final Duration ACCESS_EXPIRY = Duration.ofMinutes(15);
private SecretKey key() {
return Keys.hmacShaKeyFor(Decoders.BASE64.decode(secret));
}
public String generateAccessToken(User user) {
return Jwts.builder()
.subject(user.getId().toString())
.claim("email", user.getEmail())
.claim("roles", user.getRoles())
.issuedAt(new Date())
.expiration(Date.from(Instant.now().plus(ACCESS_EXPIRY)))
.signWith(key())
.compact();
}
public Claims validateAndParse(String token) {
return Jwts.parser()
.verifyWith(key())
.build()
.parseSignedClaims(token)
.getPayload();
}
}
The secret must be at least 256 bits (32 bytes) for HS256. Generate it once and store it in your secrets manager, not in application.yml committed to git:
openssl rand -base64 32
The filter
@Component
@RequiredArgsConstructor
public class JwtAuthFilter extends OncePerRequestFilter {
private final JwtService jwtService;
private final UserDetailsService userDetailsService;
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain chain) throws ServletException, IOException {
String header = request.getHeader(HttpHeaders.AUTHORIZATION);
if (header == null || !header.startsWith("Bearer ")) {
chain.doFilter(request, response);
return;
}
String token = header.substring(7);
try {
Claims claims = jwtService.validateAndParse(token);
String userId = claims.getSubject();
if (userId != null && SecurityContextHolder.getContext().getAuthentication() == null) {
UserDetails userDetails = userDetailsService.loadUserByUsername(userId);
UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken(
userDetails, null, userDetails.getAuthorities());
auth.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
SecurityContextHolder.getContext().setAuthentication(auth);
}
} catch (JwtException e) {
// Token invalid or expired — let the request proceed unauthenticated
// The security config will reject it at the endpoint level
}
chain.doFilter(request, response);
}
}
I catch JwtException broadly here rather than differentiating expired vs. tampered. From the filter's perspective the right behavior is the same: don't authenticate. The client should catch the 401 and attempt a refresh.
Logout
Logout needs to revoke the refresh token and clear the cookie:
@PostMapping("/auth/logout")
public ResponseEntity<Void> logout(
@CookieValue(name = "refresh_token", required = false) String refreshTokenId,
HttpServletResponse response) {
if (refreshTokenId != null) {
refreshTokenService.revoke(refreshTokenId);
}
ResponseCookie cleared = ResponseCookie.from("refresh_token", "")
.httpOnly(true)
.secure(true)
.sameSite("Strict")
.path("/auth/refresh")
.maxAge(0)
.build();
response.addHeader(HttpHeaders.SET_COOKIE, cleared.toString());
return ResponseEntity.noContent().build();
}
Setting maxAge(0) tells the browser to delete the cookie immediately.
What I skip in this setup
A few things I deliberately leave out of a standard deployment:
JWT blocklist for access tokens. Once you have 15-minute expiry and a working refresh flow, blocking access tokens before expiry is usually not worth the latency of a blocklist check on every request. If you need immediate revocation (e.g. "terminate all sessions now"), revoke all refresh tokens — the access tokens will expire naturally within 15 minutes.
RS256 asymmetric signing. Useful if multiple services need to verify tokens without sharing the secret. In a monolith or a small microservices setup where the auth service also issues tokens to itself, HMAC-SHA256 is simpler and faster.
Remember me / device management. Out of scope here, but the refresh token table already gives you the foundation: add a deviceName column, show the user their active sessions, let them revoke specific ones.
The only thing preventing most teams from shipping this instead of the tutorial version is the extra thirty minutes it takes to add the refresh token table and rotation logic. It's worth it.
What does your current JWT setup look like — are you doing refresh rotation, or relying on long-lived tokens?
Originally published on Medium.
Top comments (0)