Mục tiêu
Sau bài này, bạn sẽ:
- Hiểu JWT (JSON Web Token) là gì và tại sao nó phù hợp cho REST API.
- Tích hợp JWT vào Spring Security để bảo vệ các API endpoint.
- Xây dựng API đăng nhập trả về token.
- Sử dụng token để truy cập các API đã được bảo vệ.
- Kiểm thử với Postman.
1. Vấn đề: REST API và xác thực phi trạng thái
Ở bài trước, chúng ta đã sử dụng form login dựa trên session. Điều này hoạt động tốt với ứng dụng web truyền thống, nhưng không phù hợp với REST API vì:
- REST API cần stateless (không lưu trạng thái). Session lưu trên server phá vỡ nguyên tắc này.
- Khi có nhiều server (load balancing), session cần được chia sẻ hoặc lưu ở nơi tập trung (Redis…).
- Ứng dụng di động, SPA (React, Angular) không tự động gửi session cookie như trình duyệt web.
Giải pháp: JWT
JWT cho phép server tạo ra một token chứa thông tin người dùng và chữ ký. Client gửi token trong header Authorization mỗi khi gọi API. Server xác thực token mà không cần lưu trạng thái.
2. JWT là gì?
JWT (JSON Web Token) là một chuỗi mã hóa gồm 3 phần, cách nhau bằng dấu chấm:
header.payload.signature
Ví dụ:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
- Header: chứa thuật toán ký (HS256, RS256) và loại token.
- Payload: chứa các claims (thông tin) như userId, username, roles, thời gian hết hạn (exp).
- Signature: được tạo bằng cách mã hóa header+payload với secret key, đảm bảo token không bị sửa đổi.
Ưu điểm:
- Không cần lưu trên server -> stateless.
- Có thể chứa thông tin (không nên nhạy cảm) để giảm số lần gọi database.
- Hoạt động tốt với mọi client (web, mobile).
3. Tổng quan kiến trúc xác thực JWT trong Spring Security
Chúng ta sẽ thay thế form login bằng một filter tùy chỉnh:
- Login -> client gửi username/password -> server tạo JWT -> trả về cho client.
- Các request sau -> client gửi JWT trong header
Authorization: Bearer <token>. - JwtRequestFilter sẽ:
- Đọc token từ header.
- Xác thực token (kiểm tra chữ ký, hết hạn…).
- Nếu hợp lệ, tạo
UsernamePasswordAuthenticationTokenvà đặt vàoSecurityContextHolder.
- SecurityConfig sẽ:
- Vô hiệu hóa form login, CSRF, session.
- Chỉ định filter tùy chỉnh.
4. Cài đặt chi tiết
4.1. Thêm dependency
Trong pom.xml, thêm:
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-api</artifactId>
<version>0.11.5</version>
</dependency>
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-impl</artifactId>
<version>0.11.5</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-jackson</artifactId>
<version>0.11.5</version>
<scope>runtime</scope>
</dependency>JJWT là thư viện tạo và xác thực JWT phổ biến.
4.2. Cấu hình JWT trong application.properties
# JWT
jwt.secret=mySecretKeyForJWTTokenGenerationAndValidation2026!@#
jwt.expiration=86400000 # 1 ngày (milliseconds)Lưu ý: Secret key nên đủ dài và phức tạp. Trong thực tế, bạn có thể dùng java.util.Base64 để mã hóa.
4.3. Lớp JwtUtils (tạo và xác thực token)
package com.example.demo.utils;
import io.jsonwebtoken.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.stereotype.Component;
import java.util.Date;
@Component
public class JwtUtils {
private static final Logger logger = LoggerFactory.getLogger(JwtUtils.class);
@Value("${jwt.secret}")
private String jwtSecret;
@Value("${jwt.expiration}")
private int jwtExpirationMs;
public String generateJwtToken(UserDetails userDetails) {
return Jwts.builder()
.setSubject(userDetails.getUsername())
.setIssuedAt(new Date())
.setExpiration(new Date((new Date()).getTime() + jwtExpirationMs))
.signWith(SignatureAlgorithm.HS512, jwtSecret)
.compact();
}
public String getUserNameFromJwtToken(String token) {
return Jwts.parser().setSigningKey(jwtSecret).parseClaimsJws(token).getBody().getSubject();
}
public boolean validateJwtToken(String authToken) {
try {
Jwts.parser().setSigningKey(jwtSecret).parseClaimsJws(authToken);
return true;
} catch (SignatureException e) {
logger.error("Invalid JWT signature: {}", e.getMessage());
} catch (MalformedJwtException e) {
logger.error("Invalid JWT token: {}", e.getMessage());
} catch (ExpiredJwtException e) {
logger.error("JWT token is expired: {}", e.getMessage());
} catch (UnsupportedJwtException e) {
logger.error("JWT token is unsupported: {}", e.getMessage());
} catch (IllegalArgumentException e) {
logger.error("JWT claims string is empty: {}", e.getMessage());
}
return false;
}
}4.4. Lớp JwtRequestFilter (filter kiểm tra token)
package com.example.demo.filter;
import com.example.demo.service.CustomUserDetailsService;
import com.example.demo.utils.JwtUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
@Component
public class JwtRequestFilter extends OncePerRequestFilter {
@Autowired
private JwtUtils jwtUtils;
@Autowired
private CustomUserDetailsService userDetailsService;
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws ServletException, IOException {
final String authorizationHeader = request.getHeader("Authorization");
String username = null;
String jwt = null;
if (authorizationHeader != null && authorizationHeader.startsWith("Bearer ")) {
jwt = authorizationHeader.substring(7);
username = jwtUtils.getUserNameFromJwtToken(jwt);
}
if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {
UserDetails userDetails = this.userDetailsService.loadUserByUsername(username);
if (jwtUtils.validateJwtToken(jwt)) {
UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(
userDetails, null, userDetails.getAuthorities());
authToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
SecurityContextHolder.getContext().setAuthentication(authToken);
}
}
chain.doFilter(request, response);
}
}4.5. Lớp JwtAuthenticationEntryPoint (xử lý khi chưa xác thực)
package com.example.demo.security;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
@Component
public class JwtAuthenticationEntryPoint implements AuthenticationEntryPoint {
@Override
public void commence(HttpServletRequest request, HttpServletResponse response,
AuthenticationException authException) throws IOException, ServletException {
response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Unauthorized");
}
}4.6. Tạo DTO cho request login và response token
package com.example.demo.dto;
import lombok.Data;
@Data
public class LoginRequest {
private String username;
private String password;
}package com.example.demo.dto;
import lombok.AllArgsConstructor;
import lombok.Data;
@Data
@AllArgsConstructor
public class JwtResponse {
private String token;
private String type = "Bearer";
private String username;
public JwtResponse(String token, String username) {
this.token = token;
this.username = username;
}
}4.7. Controller xử lý login
package com.example.demo.controller;
import com.example.demo.dto.JwtResponse;
import com.example.demo.dto.LoginRequest;
import com.example.demo.utils.JwtUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/auth")
public class AuthController {
@Autowired
private AuthenticationManager authenticationManager;
@Autowired
private JwtUtils jwtUtils;
@PostMapping("/login")
public JwtResponse authenticateUser(@RequestBody LoginRequest loginRequest) {
Authentication authentication = authenticationManager.authenticate(
new UsernamePasswordAuthenticationToken(loginRequest.getUsername(), loginRequest.getPassword()));
SecurityContextHolder.getContext().setAuthentication(authentication);
UserDetails userDetails = (UserDetails) authentication.getPrincipal();
String jwt = jwtUtils.generateJwtToken(userDetails);
return new JwtResponse(jwt, userDetails.getUsername());
}
}4.8. Cập nhật SecurityConfig
package com.example.demo.config;
import com.example.demo.filter.JwtRequestFilter;
import com.example.demo.security.JwtAuthenticationEntryPoint;
import com.example.demo.service.CustomUserDetailsService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Autowired
private CustomUserDetailsService userDetailsService;
@Autowired
private JwtAuthenticationEntryPoint unauthorizedHandler;
@Autowired
private JwtRequestFilter jwtRequestFilter;
@Bean
public PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder();
}
@Bean
public AuthenticationManager authenticationManager(HttpSecurity http) throws Exception {
return http.getSharedObject(AuthenticationManagerBuilder.class)
.userDetailsService(userDetailsService)
.passwordEncoder(passwordEncoder())
.and()
.build();
}
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.cors().and().csrf().disable()
.exceptionHandling().authenticationEntryPoint(unauthorizedHandler).and()
.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS).and()
.authorizeHttpRequests(auth -> auth
.requestMatchers("/api/auth/**").permitAll()
.requestMatchers("/api/products/**").hasRole("USER")
.anyRequest().authenticated()
);
http.addFilterBefore(jwtRequestFilter, UsernamePasswordAuthenticationFilter.class);
return http.build();
}
}Giải thích:
sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS): vô hiệu hóa session.csrf().disable(): JWT không yêu cầu CSRF (vì không dùng cookie).addFilterBefore: đặt JwtRequestFilter trước UsernamePasswordAuthenticationFilter để kiểm tra token trước.
4.9. Tạo một API mẫu yêu cầu xác thực
Ví dụ, tạo một ProductController mới cho REST API (hoặc tận dụng API cũ) và bảo vệ nó bằng JWT.
package com.example.demo.controller;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/products")
public class ProductApiController {
@GetMapping
@PreAuthorize("hasRole('USER')")
public String getAllProducts() {
return "List of products (JWT protected)";
}
}Lưu ý: Để sử dụng @PreAuthorize, bạn cần bật @EnableGlobalMethodSecurity trong SecurityConfig hoặc lớp cấu hình riêng. Thêm vào SecurityConfig:
@EnableGlobalMethodSecurity(prePostEnabled = true)5. Kiểm thử với Postman
- Đăng nhập
POSThttp://localhost:8080/api/auth/login
Body (JSON):
{
"username": "admin",
"password": "admin"
}Response:
{
"token": "eyJhbGciOiJIUzUxMiJ9...",
"type": "Bearer",
"username": "admin"
}- Gọi API được bảo vệ
GEThttp://localhost:8080/api/products
Headers:Authorization: Bearer <token-copy-from-above>Nếu thành công, nhận được message. - Thử gọi API mà không có token → 401 Unauthorized.
Gọi với token sai → 401.
6. Giải thích luồng hoạt động
- Client gửi
username/passwordđến/api/auth/login. AuthenticationManagerxác thực thông tin dựa trênUserDetailsServicevàPasswordEncoder.- Nếu thành công,
JwtUtilstạo token chứa username và thời gian hết hạn, ký bằng secret key. - Client nhận token, lưu lại (có thể trong localStorage, sessionStorage, hoặc state của SPA).
- Mỗi request API tiếp theo, client gửi token trong header
Authorization. JwtRequestFilterđọc token, xác thực, nếu hợp lệ thì tạoAuthenticationobject và đặt vàoSecurityContextHolder.- Spring Security cho phép request đi tiếp dựa trên
authorizeHttpRequestsvà các annotation@PreAuthorize.
7. Tổng kết
- JWT giúp xác thực stateless cho REST API.
- Chúng ta đã tích hợp JWT vào Spring Security bằng cách:
- Tạo
JwtUtilsđể tạo và xác thực token. - Tạo
JwtRequestFilterđể kiểm tra token trong mỗi request. - Tạo endpoint login trả về token.
- Cấu hình SecurityContext vô hiệu hóa session và thêm filter.
- Tạo
- Bảo vệ các API bằng
hasRole()hoặc@PreAuthorize.
8. Bài tập
- Thêm role
ADMINvào JWT payload và kiểm tra quyền trên API (chỉ admin mới được xóa sản phẩm). - Tích hợp JWT với ứng dụng Thymeleaf (cách gửi token từ client?).
- Xây dựng API refresh token để cấp mới token khi hết hạn mà không cần đăng nhập lại.
- Chuyển secret key và thời gian hết hạn vào biến môi trường (hoặc dùng
@Valuetừ properties) để an toàn hơn.
