In modern applications, security is paramount, and JSON Web Tokens (JWTs) have become a popular choice for implementing stateless authentication. However, JWTs have an inherent limitation: once issued, they cannot be revoked or updated, which makes managing session expiration and renewal a challenge. This is where refresh tokens come in, allowing us to extend the validity of a user session without compromising security.
In this article, we’ll explore how to implement JWT refresh tokens in a Spring Security-based application, covering both the theory and practical implementation.
1. Understanding Refresh Tokens
A refresh token complements the short-lived access token by:
- Allowing users to stay logged in without requiring them to reauthenticate frequently.
- Enabling seamless token rotation, reducing the risk of token misuse.
- Supporting logout functionality by maintaining refresh token invalidation in storage.
Unlike access tokens, refresh tokens are stored securely (e.g., in HTTP-only cookies) and are used to request new access tokens when the old ones expire.
2. High-Level Architecture
A typical JWT authentication flow with refresh tokens involves:
- User Authentication: The user logs in, and the server generates an access token and a refresh token.
- Token Storage: The access token is stored on the client side (e.g., in local storage), while the refresh token is stored in a secure location.
- Access Token Expiry: When the access token expires, the client sends the refresh token to the server to get a new access token.
- Token Revocation: Refresh tokens can be invalidated server-side when a user logs out or when suspicious activity is detected.
3. Implementing JWT Refresh Tokens in Spring Security
Step 1: Configure Dependencies
Add the necessary dependencies to your pom.xml for Spring Boot, Spring Security, and JWT.
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt</artifactId>
<version>0.9.1</version>
</dependency>
Step 2: Create Token Utility Class
Implement a utility class to handle JWT creation and validation.
import io.jsonwebtoken.*;
import org.springframework.stereotype.Component;
import java.util.Date;
@Component
public class JwtTokenUtil {
private static final String SECRET_KEY = "your-secret-key";
private static final long ACCESS_TOKEN_VALIDITY = 5 * 60 * 1000; // 5 minutes
private static final long REFRESH_TOKEN_VALIDITY = 7 * 24 * 60 * 60 * 1000; // 7 days
public String generateAccessToken(String username) {
return Jwts.builder()
.setSubject(username)
.setIssuedAt(new Date())
.setExpiration(new Date(System.currentTimeMillis() + ACCESS_TOKEN_VALIDITY))
.signWith(SignatureAlgorithm.HS512, SECRET_KEY)
.compact();
}
public String generateRefreshToken(String username) {
return Jwts.builder()
.setSubject(username)
.setIssuedAt(new Date())
.setExpiration(new Date(System.currentTimeMillis() + REFRESH_TOKEN_VALIDITY))
.signWith(SignatureAlgorithm.HS512, SECRET_KEY)
.compact();
}
public boolean validateToken(String token) {
try {
Jwts.parser().setSigningKey(SECRET_KEY).parseClaimsJws(token);
return true;
} catch (JwtException ex) {
return false;
}
}
public String getUsernameFromToken(String token) {
return Jwts.parser()
.setSigningKey(SECRET_KEY)
.parseClaimsJws(token)
.getBody()
.getSubject();
}
}
Step 3: Create the Authentication Controller
Build a REST controller to handle authentication and token renewal.
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.HashMap;
import java.util.Map;
@RestController
@RequestMapping("/auth")
public class AuthController {
@Autowired
private JwtTokenUtil jwtTokenUtil;
@PostMapping("/login")
public ResponseEntity<?> login(@RequestBody LoginRequest request) {
// Authenticate user (use your existing authentication mechanism)
String username = request.getUsername(); // Mocked for simplicity
String accessToken = jwtTokenUtil.generateAccessToken(username);
String refreshToken = jwtTokenUtil.generateRefreshToken(username);
Map<String, String> tokens = new HashMap<>();
tokens.put("accessToken", accessToken);
tokens.put("refreshToken", refreshToken);
return ResponseEntity.ok(tokens);
}
@PostMapping("/refresh")
public ResponseEntity<?> refreshToken(@RequestBody RefreshTokenRequest request) {
String refreshToken = request.getRefreshToken();
if (jwtTokenUtil.validateToken(refreshToken)) {
String username = jwtTokenUtil.getUsernameFromToken(refreshToken);
String newAccessToken = jwtTokenUtil.generateAccessToken(username);
Map<String, String> tokens = new HashMap<>();
tokens.put("accessToken", newAccessToken);
return ResponseEntity.ok(tokens);
}
return ResponseEntity.status(403).body("Invalid refresh token");
}
}
class LoginRequest {
private String username;
private String password;
// Getters and Setters
}
class RefreshTokenRequest {
private String refreshToken;
// Getters and Setters
}
Step 4: Secure Refresh Tokens
Ensure refresh tokens are securely stored. For example:
- Use HTTP-only cookies to store refresh tokens, making them inaccessible via JavaScript.
- Implement a blacklist mechanism to invalidate refresh tokens on logout.
Step 5: Test the Workflow
- Test the
/auth/loginendpoint to obtain access and refresh tokens. - Use the refresh token with
/auth/refreshto generate new access tokens after the previous one expires.
4. Best Practices
To ensure a secure and efficient implementation of JWT refresh tokens, it’s important to follow best practices. These guidelines help mitigate potential vulnerabilities and enhance the overall reliability of your authentication system. Below is a table summarizing the key best practices:
| Best Practice | Description | Benefit |
|---|---|---|
| Short-Lived Access Tokens | Keep access tokens valid for a short duration, such as 5–15 minutes. | Reduces the exposure window in case of token compromise. |
| Secure Token Storage | Store refresh tokens in HTTP-only cookies or encrypted storage. | Prevents client-side access to tokens, reducing the risk of XSS attacks. |
| Implement Token Revocation | Use a server-side blacklist or database to invalidate refresh tokens when needed (e.g., logout). | Allows you to block compromised or inactive tokens effectively. |
| Use Token Rotation | Issue a new refresh token each time an access token is refreshed. | Minimizes the risk of token reuse and enhances security in case of token interception. |
| Monitor Token Usage | Track usage patterns and detect anomalies (e.g., multiple uses of the same refresh token). | Helps identify potential security breaches or token theft. |
| Implement Expiry for Refresh Tokens | Set an expiration time for refresh tokens (e.g., 7 days). | Ensures that old, unused tokens are not valid indefinitely. |
| Secure Communication | Use HTTPS to encrypt all communication between client and server. | Prevents tokens from being intercepted during transmission. |
By adopting these best practices, you can significantly improve the security and reliability of your JWT-based authentication system, safeguarding user data and ensuring a seamless user experience.
5. Conclusion
JWT refresh tokens provide a robust way to manage user authentication in stateless architectures. By leveraging Spring Security, you can create a secure and scalable authentication mechanism that ensures seamless user sessions while minimizing security risks.
With the approach outlined in this guide, you’ll have the foundation needed to implement and customize JWT refresh token handling in your Spring Security projects.
