JWT Authentication in Spring Boot: A Complete Step-by-Step Tutorial

<dependencies>
<!-- Spring Web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Spring Security -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

<!-- JJWT - JWT generation and validation -->
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.12.5</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>0.12.5</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-jackson</artifactId>
    <version>0.12.5</version>
    <scope>runtime</scope>
</dependency>

<!-- Validation -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

app:
  jwt:
    secret: "404E635266556A586E3272357538782F413F4428472B4B6250645367566B5970"
    # Generate your own: openssl rand -hex 32
    expiry-ms: 86400000  # 24 hours in milliseconds

@Component
public class JwtUtils {
@Value("${app.jwt.secret}")
private String jwtSecret;

@Value("${app.jwt.expiry-ms}")
private long jwtExpiryMs;

// Generate a JWT token for a successfully authenticated user
public String generateToken(UserDetails userDetails) {
    return Jwts.builder()
        .subject(userDetails.getUsername())
        .claim("roles", userDetails.getAuthorities().stream()
            .map(GrantedAuthority::getAuthority)
            .collect(Collectors.toList()))
        .issuedAt(new Date())
        .expiration(new Date(System.currentTimeMillis() + jwtExpiryMs))
        .signWith(getSigningKey())
        .compact();
}

// Extract username (subject) from a token
public String extractUsername(String token) {
    return extractClaims(token).getSubject();
}

// Check if token is valid for the given user and not expired
public boolean isTokenValid(String token, UserDetails userDetails) {
    try {
        final String username = extractUsername(token);
        return username.equals(userDetails.getUsername())
            && !isTokenExpired(token);
    } catch (JwtException e) {
        return false; // invalid signature, malformed, etc.
    }
}

private boolean isTokenExpired(String token) {
    return extractClaims(token).getExpiration().before(new Date());
}

private Claims extractClaims(String token) {
    return Jwts.parser()
        .verifyWith(getSigningKey())
        .build()
        .parseSignedClaims(token)
        .getPayload();
}

private SecretKey getSigningKey() {
    byte[] keyBytes = Decoders.BASE64.decode(jwtSecret);
    return Keys.hmacShaKeyFor(keyBytes);
}
}

// User entity - stored in database
@Entity
@Table(name = "users")
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long   id;

@Column(unique = true, nullable = false)
private String email;

@Column(nullable = false)
private String password; // stored as BCrypt hash

@Enumerated(EnumType.STRING)
private Role role; // ROLE_USER, ROLE_ADMIN

// getters and setters...
}
public enum Role { ROLE_USER, ROLE_ADMIN }
public interface UserRepository extends JpaRepository<User, Long> {
Optional<User> findByEmail(String email);
}
// UserDetailsService - Spring Security calls this to load user by username
@Service
public class UserDetailsServiceImpl implements UserDetailsService {
private final UserRepository userRepository;

public UserDetailsServiceImpl(UserRepository userRepository) {
    this.userRepository = userRepository;
}

@Override
public UserDetails loadUserByUsername(String email) throws UsernameNotFoundException {
    User user = userRepository.findByEmail(email)
        .orElseThrow(() -> new UsernameNotFoundException("User not found: " + email));

    return org.springframework.security.core.userdetails.User.builder()
        .username(user.getEmail())
        .password(user.getPassword())   // already BCrypt hashed in DB
        .roles(user.getRole().name().replace("ROLE_", "")) // Spring adds ROLE_ prefix
        .build();
}
}

@Component
public class JwtAuthFilter extends OncePerRequestFilter {
private final JwtUtils           jwtUtils;
private final UserDetailsService userDetailsService;

public JwtAuthFilter(JwtUtils jwtUtils, UserDetailsService uds) {
    this.jwtUtils           = jwtUtils;
    this.userDetailsService = uds;
}

@Override
protected void doFilterInternal(
        HttpServletRequest  request,
        HttpServletResponse response,
        FilterChain         filterChain) throws ServletException, IOException {

    // Step 1: Read the Authorization header
    final String authHeader = request.getHeader("Authorization");

    // Step 2: If no Bearer token, skip - let Spring Security handle it
    if (authHeader == null || !authHeader.startsWith("Bearer ")) {
        filterChain.doFilter(request, response);
        return;
    }

    // Step 3: Extract the token (remove "Bearer " prefix)
    final String jwt      = authHeader.substring(7);
    final String username = jwtUtils.extractUsername(jwt);

    // Step 4: If username found and no existing auth in context
    if (username != null &&
        SecurityContextHolder.getContext().getAuthentication() == null) {

        // Step 5: Load user details from DB
        UserDetails userDetails = userDetailsService.loadUserByUsername(username);

        // Step 6: Validate token against loaded user
        if (jwtUtils.isTokenValid(jwt, userDetails)) {

            // Step 7: Create authentication token and set in SecurityContext
            UsernamePasswordAuthenticationToken authToken =
                new UsernamePasswordAuthenticationToken(
                    userDetails,
                    null,                          // credentials - null after auth
                    userDetails.getAuthorities()  // roles from UserDetails
                );
            authToken.setDetails(
                new WebAuthenticationDetailsSource().buildDetails(request));

            SecurityContextHolder.getContext().setAuthentication(authToken);
            // From here, the request is "authenticated" for this thread
        }
    }

    // Step 8: Continue to next filter / controller
    filterChain.doFilter(request, response);
}
}

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {
private final JwtAuthFilter          jwtAuthFilter;
private final UserDetailsServiceImpl  userDetailsService;

public SecurityConfig(JwtAuthFilter jwtFilter,
                       UserDetailsServiceImpl uds) {
    this.jwtAuthFilter     = jwtFilter;
    this.userDetailsService = uds;
}

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http)
        throws Exception {

    return http
        .csrf(csrf -> csrf.disable())
        .sessionManagement(session -> session
            .sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .authorizeHttpRequests(auth -> auth
            // Public endpoints - no token required
            .requestMatchers("/api/auth/login").permitAll()
            .requestMatchers("/api/auth/register").permitAll()
            .requestMatchers(HttpMethod.GET, "/api/products/**").permitAll()
            // Admin-only endpoints
            .requestMatchers("/api/admin/**").hasRole("ADMIN")
            // All other requests need a valid JWT
            .anyRequest().authenticated())
        // Register our JWT filter before Spring's default auth filter
        .addFilterBefore(jwtAuthFilter,
            UsernamePasswordAuthenticationFilter.class)
        .build();
}

@Bean
public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
}

@Bean
public AuthenticationManager authenticationManager(
        AuthenticationConfiguration config) throws Exception {
    return config.getAuthenticationManager();
}
}

// Request and response records
public record LoginRequest(@NotBlank String email, @NotBlank String password) {}
public record RegisterRequest(@Email String email, @Size(min=8) String password) {}
public record AuthResponse(String token, String email, String role) {}
@RestController
@RequestMapping("/api/auth")
public class AuthController {
private final AuthenticationManager  authManager;
private final UserDetailsServiceImpl  userDetailsService;
private final UserRepository          userRepository;
private final PasswordEncoder         passwordEncoder;
private final JwtUtils               jwtUtils;

public AuthController(AuthenticationManager am, UserDetailsServiceImpl uds,
                       UserRepository ur, PasswordEncoder pe, JwtUtils ju) {
    this.authManager        = am;
    this.userDetailsService = uds;
    this.userRepository     = ur;
    this.passwordEncoder    = pe;
    this.jwtUtils           = ju;
}

@PostMapping("/login")
public ResponseEntity<AuthResponse> login(@Valid @RequestBody LoginRequest req) {

    // Throws BadCredentialsException if invalid - caught by @RestControllerAdvice
    authManager.authenticate(
        new UsernamePasswordAuthenticationToken(req.email(), req.password()));

    // Authentication succeeded - generate token
    UserDetails userDetails = userDetailsService.loadUserByUsername(req.email());
    String      token       = jwtUtils.generateToken(userDetails);

    return ResponseEntity.ok(new AuthResponse(token, req.email(), "ROLE_USER"));
}

@PostMapping("/register")
public ResponseEntity<AuthResponse> register(@Valid @RequestBody RegisterRequest req) {

    if (userRepository.findByEmail(req.email()).isPresent()) {
        throw new EmailAlreadyExistsException("Email already registered");
    }

    User newUser = new User();
    newUser.setEmail(req.email());
    newUser.setPassword(passwordEncoder.encode(req.password())); // BCrypt hash
    newUser.setRole(Role.ROLE_USER);
    userRepository.save(newUser);

    UserDetails userDetails = userDetailsService.loadUserByUsername(req.email());
    String      token       = jwtUtils.generateToken(userDetails);

    return ResponseEntity.status(201).body(new AuthResponse(token, req.email(), "ROLE_USER"));
}
}

@RestController
@RequestMapping("/api/products")
public class ProductController {
private final ProductService productService;

public ProductController(ProductService productService) {
    this.productService = productService;
}

// Public - any user, no token needed (matched in SecurityFilterChain)
@GetMapping
public List<ProductDto> getAll() {
    return productService.findAll();
}

// Any authenticated user - needs valid JWT
@GetMapping("/{id}")
@PreAuthorize("isAuthenticated()")
public ResponseEntity<ProductDto> getById(@PathVariable Long id) {
    return ResponseEntity.ok(productService.findById(id));
}

// ADMIN only - must have ROLE_ADMIN in JWT claims
@PostMapping
@PreAuthorize("hasRole('ADMIN')")
public ResponseEntity<ProductDto> create(@Valid @RequestBody CreateProductRequest req) {
    return ResponseEntity.status(201).body(productService.create(req));
}

@DeleteMapping("/{id}")
@PreAuthorize("hasRole('ADMIN')")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void delete(@PathVariable Long id) {
    productService.delete(id);
}

// Access own resource only - uses JWT subject (email) in expression
@GetMapping("/my-orders")
@PreAuthorize("#email == authentication.principal.username")
public List<OrderDto> myOrders(@RequestParam String email) {
    return orderService.findByEmail(email);
}
}