Spring Security JWT Implementation Guide

In modern microservices and high-concurrency web application development, JSON Web Token (JWT)-based authentication has become the industry standard. As one of the most powerful security frameworks in the Java ecosystem, Spring Security provides robust mechanisms to support JWT issuance and validation processes. This article delves into how to integrate JWT within a Spring Boot project to implement a stateless user identity verification system.
Traditional web authentication relies on server-side session management. Upon successful login, the server generates a Session ID in memory or database and returns it to the client; subsequent requests carry this ID for the server to query permission status. This approach suffers from obvious single points of failure risks, poor scalability, and difficulties with cross-domain support.

In contrast, JWT is an open standard JSON format data structure containing a Header (头), Payload (有效载荷), and Signature (签名). Its core advantage lies in being "stateless": once the user obtains a Token, the server can verify identity without storing session information. The client sends the JWT to the backend within the Authorization field of the HTTP Header; the server only needs to parse and validate the signature's legitimacy to complete authentication.

Filter Chain Configuration in Spring Security

To enable JWT authentication in a Spring Boot project, it is crucial to correctly configure the order and rules of security filters. By default, Spring Security uses mechanisms based on form or basic authentication; we need to replace these with custom JwtAuthenticationEntryPoint (used for denying access) and UserDetailsService (for loading user information).

First, define JWT-related parameters in the configuration file application.yml:

jwt:
  secret-key: your-secret-key-here-32-characters-long-or-more
  expiration-time: 86400 # Unit is milliseconds, i.e., one day
  header-name: Authorization
  prefix-value: Bearer

Next comes the core configuration class JwtAuthenticationFilter. This filter intercepts all requests, extracts the JWT Token, and verifies whether the signature is valid and if the expiration time is correct:

  1. If no Token is carried, deny access directly and return a 401 status code;
  2. If the Token is invalid or has expired, similarly deny access;
  3. If verification passes, extract user information (such as username) from the Header and encapsulate it into a UsernamePasswordAuthenticationToken object.
@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {
    @Autowired private UserService userService; // Used to load user details
    
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        String authHeader = request.getHeader(JwtAuthConfig.HEADER_NAME);
        
        if (authHeader == null || !authHeader.startsWith(JwtAuthConfig.PREFIX_VALUE)) {
            // No valid Token carried, deny access
            throw new JwtException("Unauthorized");
        }

        try {
            String token = authHeader.substring(7).trim();
            Claims claims = Jwts.parser().setSigningKey(new SecretKeySpec(JwtAuthConfig.SECRET_KEY.getBytes(), "HS256")).parseClaimsJws(token).getBody();
            
            // Build authentication object, injecting username into SecurityContext for subsequent interceptors to use
            UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(claims.getSubject().toString(), null, Collections.emptyList());
            filterChain.doFilter(request, response);
        } catch (Exception e) {
            // Token invalid or expired, deny access
            throw new JwtException("Unauthorized");
        }
    }
}

Finally, register this filter in WebSecurityConfigurerAdapter (or the newer Spring Security 6+ configuration style):

  • Set security policy to "authentication required for any request";
  • Add the custom JWT filter to the very beginning of the filter chain to ensure identity verification is completed before business logic execution.

User Information Loading and Permission Control Implementation

Although Spring Security natively supports Role-Based Access Control (RBAC), upon introducing JWT, we must explicitly determine how to retrieve the current logged-in user's identity information for subsequent authorization judgments. This is typically achieved through a custom UserDetailsService interface implementation:

  • Accept username as a parameter;
  • Query the corresponding user object from database or cache;
  • Return a User entity containing detailed information such as role lists and permission sets.

Furthermore, one can combine Spring Security Expression Language (SpEL) to write dynamic rule expressions (such as hasRole('ADMIN')), intercepting specific interfaces in Controller layers for access control, thereby constructing a fine-grained permission management system.

Precautions and Best Practices in Actual Development

When deploying the JWT + Spring Security solution in practice, keep the following points in mind:

  • Secret Key Management: The Secret Key is the core basis for generating signatures; it must be kept secure and rotated regularly. It is recommended to inject via environment variables or configuration center rather than hardcoding into code.
  • Time Synchronization Issues: Since servers do not store session state, having all nodes share the same Secret Key and clock source is critical. If there are significant time deviations between servers (e.g., exceeding Token validity), legitimate users may be mistakenly judged as unauthorized accessors. It is recommended to use NTP services uniformly for system time calibration.
  • Token Refresh Mechanism: For long-lifecycle JWTs, a "short-lived Access Token + long-lived Refresh Token" dual-token mode can be designed. When the Access Token expires, the client uses the Refresh Token to request a new Access Token, avoiding frequent re-logins.

Through the above steps, we have successfully built a stateless identity authentication system based on Spring Security and JWT. This solution not only enhances scalability and availability but also lays a solid foundation for distributed authorization in subsequent microservice architectures. Developers can further expand functional modules according to specific business requirements to implement more complex security policy configurations and user behavior auditing capabilities.