Click on any component in the architecture to understand how stateless JWT authentication works.

Simulation Legend

Credentials (User/Pass)

JWT Bearer Token

Invalid / Expired Access

Req

Frontend / Client

Phase 1: Authentication

AuthController

POST /api/auth/login

AuthenticationManager

Verifies Hash in DB

JwtService

Secret Key HS256

Phase 2: Authorization

JwtAuthenticationFilter

Extracts 'Bearer <token>'

SecurityContextHolder

Sets User State Temporarily

Protected Controller

GET /api/users/profile

Stateless Authentication with JWT

JSON Web Tokens (JWT) provide a stateless mechanism for authenticating API requests. Instead of storing a session ID in server memory/database, the server cryptographically signs a JSON payload containing the user's identity and roles, and sends it to the client.

1. Header

Specifies the algorithm used to sign the token (e.g., HS256) and the token type (JWT).

2. Payload (Claims)

Contains the actual data: `sub` (username), `exp` (expiration time), and custom claims like roles.

3. Signature

Created by hashing the Header + Payload using a secret key known *only* to the server. Ensures integrity.

Core Implementations

1. The JwtService (Using io.jsonwebtoken library)

This class is responsible for generating new tokens during login and validating incoming tokens on subsequent requests.

@Service
public class JwtService {
    @Value("${jwt.secret}")
    private String secretKey; // Must be 256-bit+ secure key

    public String generateToken(UserDetails userDetails) {
        return Jwts.builder()
            .setSubject(userDetails.getUsername())
            .claim("roles", userDetails.getAuthorities())
            .setIssuedAt(new Date(System.currentTimeMillis()))
            .setExpiration(new Date(System.currentTimeMillis() + 1000 * 60 * 60 * 10)) // 10 hours
            .signWith(getSigningKey(), SignatureAlgorithm.HS256)
            .compact();
    }

    public String extractUsername(String token) {
        return Jwts.parserBuilder()
            .setSigningKey(getSigningKey())
            .build()
            .parseClaimsJws(token) // Throws exception if signature is invalid or expired
            .getBody()
            .getSubject();
    }
}

2. The JwtAuthenticationFilter

This filter intercepts every incoming request. It extracts the token from the `Authorization: Bearer` header, validates it using the `JwtService`, and populates the Spring `SecurityContextHolder` so controllers know who is making the request.

@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    @Autowired private JwtService jwtService;
    @Autowired private UserDetailsService userDetailsService;

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
            
        final String authHeader = request.getHeader("Authorization");
        
        // 1. Check if token exists
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            chain.doFilter(request, response);
            return;
        }

        // 2. Extract Token
        final String jwt = authHeader.substring(7);
        final String username = jwtService.extractUsername(jwt);

        // 3. If token valid and context is empty, set authentication
        if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {
            UserDetails userDetails = this.userDetailsService.loadUserByUsername(username);
            
            if (jwtService.isTokenValid(jwt, userDetails)) {
                UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(
                        userDetails, null, userDetails.getAuthorities());
                
                // Save user details to Context for this request lifecycle
                SecurityContextHolder.getContext().setAuthentication(authToken);
            }
        }
        
        // 4. Continue filter chain
        chain.doFilter(request, response);
    }
}

The client application (React, Angular, Mobile App) interacts with the server in two distinct ways:

Login: Sends raw credentials via POST. Expects a JWT string in response.
Requests: Attaches the received JWT to the HTTP Header: Authorization: Bearer eyJhbGci... for all subsequent secured API calls.

The exposed public endpoint (e.g., /api/auth/login) designed to handle authentication requests.

It receives the username and password from the client request body and passes them to the AuthenticationManager to verify if they are correct.

Spring Security's core component for validating credentials.

It uses an AuthenticationProvider (usually DaoAuthenticationProvider) to fetch the user's encoded password from the database (via UserDetailsService) and compares it against the raw password provided in the request using a PasswordEncoder (like BCrypt).

The cryptographic brain of the operation. It has two main jobs:

1. Sign (Generate): Takes verified user details, builds a JSON payload, and hashes it using a highly secure, server-side secret key (e.g., HMAC-SHA256).

2. Verify (Parse): Takes an incoming token, recalculates the signature using the server's secret key, and compares it. If they match, the token wasn't tampered with. It also checks the exp (expiration) claim.

A custom filter extending OncePerRequestFilter, placed early in the Spring Security Filter Chain.

It intercepts every request, looking for the Authorization header. If it finds a Bearer token, it extracts it and sends it to the JwtService for verification.

If the JwtAuthenticationFilter determines the token is valid, it extracts the username and roles, creates an Authentication object, and places it in the SecurityContext.

Because JWT is stateless, the server doesn't remember this context between requests. The filter must rebuild this context on every single request using the provided token.

Your actual business logic endpoints (e.g., @GetMapping("/api/profile")).

By the time the request reaches here, Spring Security has already guaranteed the user is authenticated. You can safely use @AuthenticationPrincipal or check roles using @PreAuthorize("hasRole('ADMIN')") based on the claims extracted from the JWT.

JWT Authentication Flow

Component Inspector