Bạn dán một JWT vào jwt.io, đọc được email và role, rồi kết luận token bị lộ. Payload của JWT vốn không bí mật: base64url chỉ là cách biểu diễn chuỗi, ai có token cũng đọc được. Thứ bảo vệ token là chữ ký và các claim được kiểm tra đúng. Trong Spring Boot 4.1, bạn cũng không cần tự viết filter JWT — oauth2ResourceServer() làm việc đó.
Mục lục
Cập nhật 2026
- Spring Security 7.1.2 trên Spring Boot 4.1.2 / Spring Framework 7.0.10, baseline Java 25 LTS.
and()đã bị bỏ khỏi DSL; mọi cấu hình dùng lambda.WebSecurityConfigurerAdapterkhông còn từ Security 6. oauth2ResourceServer().jwt()tự tríchAuthorization: Bearer, xác minh chữ ký, kiểm traiss/aud/expvà trả 401 kèmWWW-Authenticate. Không cần thêmjjwt.- Bên dưới là Nimbus JOSE (
nimbus-jose-jwt) trongspring-security-oauth2-jose; không cần pin version Nimbus. - Boot có property
spring.security.oauth2.resourceserver.jwt.audiences, và@MockitoBeanthay@MockBean.
JWT được cấu tạo từ gì?
JWT là chuỗi ba phần ngăn bằng dấu chấm: header.payload.signature. Header mô tả alg, typ và kid (id của key đã ký). Payload chứa các claim. Signature là kết quả ký trên đúng chuỗi base64url(header) + "." + base64url(payload).
Cả ba phần dùng base64url — bảng chữ cái an toàn cho URL, bỏ padding =. Payload đọc được mà không cần secret:
var token = "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIn0.eyJzdWIiOiJ1LTQyIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZXZvdGVrLnZuIiwicm9sZXMiOlsiVVNFUiJdfQ.c2ln";
var parts = token.split("\\.");
var payload = new String(java.util.Base64.getUrlDecoder()
.decode(parts[1]), java.nio.charset.StandardCharsets.UTF_8);
System.out.println(payload);
// {"sub":"u-42","aud":"https://api.evotek.vn","roles":["USER"]}
Base64url không phải mã hóa. Nó không có key và không che dữ liệu, nên đừng đặt email, số điện thoại hay số thẻ trong payload. Nếu nội dung buộc phải kín, bạn cần JWE (RFC 7516), không phải JWS. Mặc định resource server của Spring xử lý JWT đã ký; JWE phải tự cấu hình decoder.
Chọn thuật toán ký: RS256, ES256 hay HS256?
| Thuật toán | Ai xác minh được | Dùng khi |
|---|---|---|
| RS256 | Mọi bên có public key, qua JWKS | Nhiều service, IdP ngoài; verifier không thể tạo token giả. |
| ES256 | Mọi bên có public key, qua JWKS | Như RS256 nhưng key và chữ ký nhỏ hơn; phù hợp mobile/IoT. |
| HS256 | Bất kỳ ai giữ secret | Một service duy nhất, secret tối thiểu 256 bit từ secret manager. |
Với RS256/ES256, authorization server giữ private key và công bố public key tại JWKS; resource server chọn key theo kid. Xoay key chỉ là thao tác vận hành: thêm key mới vào JWKS, giữ key cũ đến khi token cũ hết hạn, rồi xóa — không downtime, không deploy lại secret.
HS256 đối xứng: ai xác minh được cũng ký được. Trong microservices, một service bị chiếm quyền có thể phát token cho toàn hệ. Chỉ dùng HS256 khi thật sự có một service và secret được quản lý nghiêm túc.
Đừng chọn thuật toán theo alg trong header. Kẻ tấn công có thể gửi alg: none (JWT không ký) hoặc ép sang thuật toán yếu hơn. Hãy để decoder được cấu hình sẵn thuật toán và key; nếu tự parse, phải allowlist alg và từ chối none trước mọi bước khác.
Claims: hợp đồng giữa issuer và resource server
Claim là dữ liệu trong payload. Nhóm registered claim có nghĩa cố định, và mỗi claim bị bỏ qua là một lỗ hổng:
iss— ai phát hành. Phải đối chiếu với issuer đã cấu hình; bỏ quaissnghĩa là token từ IdP khác cũng được chấp nhận.aud— API nào được dùng token. Thiếu kiểm tra này, token cấp cho service A gọi được service B.sub— định danh chủ thể, nên là ID bất biến thay vì email. Dùngsubđể tra quyền sở hữu dữ liệu, không phải bằng chứng đủ để truy cập mọi bản ghi.exp,iat,nbf— hết hạn, phát hành, bắt đầu hiệu lực.jti— ID duy nhất của token, dùng cho denylist và audit.scope/scp— quyền OAuth2. Converter mặc định đọcscopevà gắn tiền tốSCOPE_, nên kiểm tra bằnghasAuthority("SCOPE_orders:read").roles— claim tùy ý. Muốn dùnghasRole("USER")phải map sang authorityROLE_USER.
Cấu hình JWT Authentication trong resource server
Bốn dependency; không cần thư viện JWT riêng vì phần xác minh đã nằm trong resource server:
| Artifact | Vai trò |
|---|---|
spring-boot-starter-webmvc |
Tầng REST; trên Boot 4.1 đây là starter được khuyến nghị thay spring-boot-starter-web. |
spring-boot-starter-security |
Filter chain và API cấu hình bảo mật. |
spring-boot-starter-oauth2-resource-server |
DSL oauth2ResourceServer, xử lý Bearer token và 401. |
spring-security-test (scope test) |
jwt() post-processor và @WithMockUser. |
Cấu hình khai báo, ngắn nhất và đúng nhất cho production:
# File: src/main/resources/application.yml
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://id.evotek.vn
jwk-set-uri: https://id.evotek.vn/.well-known/jwks.json
audiences:
- https://api.evotek.vn
issuer-uri vừa là giá trị phải khớp claim iss, vừa cho phép Spring tìm metadata và JWKS. Khi IdP không có metadata endpoint, hoặc không muốn phụ thuộc discovery, khai báo thêm jwk-set-uri; Spring vẫn kiểm tra iss nhờ issuer-uri.
// File: src/main/java/vn/evotek/orders/security/SecurityConfig.java
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {
@Bean
SecurityFilterChain api(HttpSecurity http, JwtAuthenticationConverter jwtConverter) throws Exception {
http
.csrf(csrf -> csrf.disable()) // API chỉ dùng Bearer token, không có cookie phiên
.sessionManagement(session ->
session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.authorizeHttpRequests(auth -> auth
.requestMatchers("/actuator/health").permitAll()
.requestMatchers(HttpMethod.GET, "/api/orders/**").hasRole("USER")
.requestMatchers(HttpMethod.DELETE, "/api/orders/**").hasRole("ADMIN")
.anyRequest().authenticated())
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(jwt -> jwt.jwtAuthenticationConverter(jwtConverter)));
return http.build();
}
@Bean
JwtAuthenticationConverter jwtAuthenticationConverter() {
JwtGrantedAuthoritiesConverter authorities = new JwtGrantedAuthoritiesConverter();
authorities.setAuthoritiesClaimName("roles");
authorities.setAuthorityPrefix("ROLE_");
JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
converter.setJwtGrantedAuthoritiesConverter(authorities);
return converter;
}
}
STATELESS bảo Spring không tạo HttpSession và không lưu SecurityContext giữa các request. oauth2ResourceServer().jwt() thay toàn bộ filter tự viết: trích token, decode, xác minh và dựng JwtAuthenticationToken. Rule theo method đặt trước anyRequest() để mỗi hành động có mức quyền riêng.
Đừng viết OncePerRequestFilter cho JWT nữa. Filter tự chế thường bỏ qua kiểm tra aud, tự parse token bằng thư viện phụ và trả 401 không có WWW-Authenticate. Nếu cần xử lý riêng, đặt nó sau BearerTokenAuthenticationFilter.
Map roles từ claim sang authority
Converter mặc định đọc scope và tạo authority SCOPE_<scope>. Với claim roles: ["USER", "ADMIN"], cấu hình trên cho ra ROLE_USER và ROLE_ADMIN, nên hasRole("USER") và @PreAuthorize("hasRole('ADMIN')") khớp.
Hai lỗi nằm ở tiền tố. Nếu claim đã là ["ROLE_ADMIN"] mà vẫn đặt prefix ROLE_, authority thành ROLE_ROLE_ADMIN và mọi kiểm tra đều 403. Ngược lại, nếu dùng setAuthorityPrefix(""), hasRole không bao giờ khớp vì nó tự thêm ROLE_. Chọn một quy ước và ghi vào tài liệu đội. Phần phân quyền chi tiết nằm ở bài RBAC trong Spring Security.
Controller không cần tra DB để biết người gọi là ai; principal mặc định là chính đối tượng Jwt:
// File: src/main/java/vn/evotek/orders/web/OrderController.java
@RestController
@RequestMapping("/api/orders")
class OrderController {
@GetMapping
List<Order> list(@AuthenticationPrincipal Jwt jwt) {
return List.of(new Order("A-100", jwt.getSubject()));
}
@PreAuthorize("hasRole('ADMIN')")
@DeleteMapping("/{id}")
void delete(@PathVariable String id) {
// kiểm tra quyền sở hữu bản ghi trước khi xóa
}
}
record Order(String id, String owner) {}
Kiểm thử với jwt() và @WithMockUser
Test resource server không cần token thật hay IdP. jwt() đặt sẵn JwtAuthenticationToken vào SecurityContext và bỏ qua decoder:
// File: src/test/java/vn/evotek/orders/web/OrderControllerTest.java
@WebMvcTest(OrderController.class)
@Import(SecurityConfig.class)
class OrderControllerTest {
@Autowired MockMvc mvc;
@MockitoBean JwtDecoder jwtDecoder; // thay @MockBean
@Test
void thieuToken_tra401() throws Exception {
mvc.perform(get("/api/orders"))
.andExpect(status().isUnauthorized());
}
@Test
void coTokenRoleUser_tra200() throws Exception {
mvc.perform(get("/api/orders").with(jwt()
.jwt(j -> j.subject("u-42").claim("roles", List.of("USER")))
.authorities(new SimpleGrantedAuthority("ROLE_USER"))))
.andExpect(status().isOk())
.andExpect(jsonPath("$[0].id").value("A-100"));
}
@Test
@WithMockUser(roles = "ADMIN")
void admin_xoaDuocDonHang() throws Exception {
mvc.perform(delete("/api/orders/A-100"))
.andExpect(status().isOk());
}
}
Điểm dễ sai: jwt() không chạy converter của bạn. Authority đến từ scope mặc định hoặc từ .authorities(...), nên test role phải tự ghi ROLE_USER; việc map claim roles cần một unit test riêng. @WithMockUser phù hợp khi chỉ cần người dùng giả với role. Với ứng dụng thật, giữ một test giải mã token ký bằng key test để bắt lỗi cấu hình aud/iss.
Nếu bạn là bên phát hành token
Resource server chỉ nên xác minh token; việc ký thuộc authorization server. Tự ký bằng JJWT hay Nimbus nghĩa là bạn sở hữu private key, JWKS, xoay key, endpoint token, refresh token và thu hồi. Hai lựa chọn đúng:
- Spring Authorization Server — nếu cần tự vận hành OAuth2/OIDC authorization server, hỗ trợ authorization code + PKCE, client credentials và refresh token. Đây là project chính thức của Spring, không phải thư viện ký JWT.
- IdP bên ngoài — Keycloak, Auth0, Microsoft Entra ID. Với đăng nhập qua Google/GitHub, dùng OIDC login như bài OAuth2 với Spring Security.
Nếu chỉ cần token nội bộ giữa vài service, dùng client credentials của IdP. Đừng dựng endpoint /login tự ký rồi gọi đó là “JWT authentication”.
Access token và refresh token
Access token ngắn hạn (5–15 phút), gửi tới resource server, mang theo quyền. Refresh token dài hạn hơn (vài ngày đến vài tuần), chỉ gửi tới token endpoint của authorization server. Lưu refresh token phía server dưới dạng hash.
Bật rotation: mỗi lần refresh, phát token mới và vô hiệu token cũ. Nếu token cũ được dùng lại, coi như bị đánh cắp và thu hồi cả family. Đây là cách phát hiện replay rẻ hơn denylist access token.
Thu hồi token
JWT không có cơ chế thu hồi sẵn. Ba lựa chọn với đánh đổi rõ ràng:
- Hết hạn ngắn — access token 5–15 phút, token cũ tự chết. Đơn giản nhất, nhưng đăng xuất không có hiệu lực tức thì.
- Denylist theo
jti— ghijtivào Redis với TTL bằngexp, kiểm tra mỗi request. Lấy lại khả năng thu hồi nhưng mất một phần stateless và thêm điểm phụ thuộc. - Opaque token + introspection — token không chứa claim, mỗi request gọi introspection tới authorization server. Thu hồi tức thì, nhưng độ trễ và tải cao hơn. Spring hỗ trợ qua
oauth2ResourceServer().opaqueToken().
Đừng dùng JWT như session store rồi than phiền không logout được: nếu cần thu hồi tức thì trên mọi thiết bị, opaque token hoặc denylist là câu trả lời.
Clock skew
exp được so với đồng hồ resource server, và đồng hồ container trôi vài giây là bình thường. Spring cho phép skew mặc định một phút qua JwtTimestampValidator. Nếu kiểm soát cả hai đầu, hạ xuống 30 giây; đừng nâng lên vài phút để “cho chắc”, vì mỗi phút skew là một phút token hết hạn vẫn được chấp nhận.
Muốn đổi skew, bạn phải tự định nghĩa JwtDecoder. Khi đó Boot không còn áp dụng audiences tự động, nên phải thêm lại validator cho iss và aud:
// File: src/main/java/vn/evotek/orders/security/JwtConfig.java
@Configuration
class JwtConfig {
@Bean
JwtDecoder jwtDecoder(
@Value("${spring.security.oauth2.resourceserver.jwt.issuer-uri}") String issuer,
@Value("${spring.security.oauth2.resourceserver.jwt.jwk-set-uri}") String jwkSetUri) {
NimbusJwtDecoder decoder = NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(
new JwtTimestampValidator(Duration.ofSeconds(30)),
new JwtIssuerValidator(issuer),
new JwtClaimValidator<List<String>>("aud",
aud -> aud != null && aud.contains("https://api.evotek.vn"))));
return decoder;
}
}
Những lỗi bảo mật thường gặp
- Chấp nhận
alg: nonehoặc tinalgtrong header. Luôn cấu hình decoder với thuật toán và key cố định; không để token tự chọn cách xác minh. - Không kiểm tra
issvàaud. Token đúng chữ ký vẫn có thể đến từ tenant khác hoặc được cấp cho API khác. - Hard-code secret trong
application.ymlhoặc git. Dùng biến môi trường hoặc secret manager; secret HS256 ngắn hơn 256 bit làm yếu HMAC. - Lưu token ở
localStorage. Mọi script trên trang đều đọc được, nên một lỗ hổng XSS là mất token. Với web same-site, ưu tiên cookieHttpOnly,Secure,SameSite; với mobile/CLI, dùng bearer header và secure storage của hệ điều hành. Cookie httpOnly đổi lại rủi ro CSRF, nên phải giữ CSRF protection nếu dùng cookie. - Access token sống 24 giờ để “đỡ phải refresh”. Token bị đánh cắp dùng được suốt 24 giờ. Hạ xuống 5–15 phút và thêm refresh token có rotation.
- Map role sai tiền tố.
ROLE_ROLE_ADMIN, hoặc claimroleskhông được đọc vì converter còn mặc định đọcscope. Viết test cho converter, đừng chỉ test controller. - Log token. Access log, exception handler, APM và trace header đều có thể ghi nguyên
Authorization. Chỉ logsub,jtivà thời điểm hết hạn; thêm rule che header. - Dùng JWT để thu hồi session. Không có denylist hoặc token ngắn hạn thì đăng xuất, khóa tài khoản và đổi quyền đều không có hiệu lực tức thì.
Khi nào dùng JWT, khi nào không
| Tình huống | Lựa chọn hợp lý |
|---|---|
| Web app same-site, một backend, cần logout tức thì | Session cookie phía server; đơn giản hơn và thu hồi được. |
| SPA/mobile + nhiều API/service | JWT access token ngắn hạn + refresh token; RS256/ES256 và JWKS. |
| Cần thu hồi tức thì | Opaque token + introspection, hoặc denylist jti. |
Nhìn sang 2027
Spring Security 7.2 và Spring Boot 4.2 hiện chỉ ở bản RC, chưa phát hành — đừng nâng production lên đó. Hướng đang rõ hơn là đăng nhập bằng passkey/WebAuthn, liên kết IdP qua OIDC, và access token ngày càng ngắn hạn hơn.
Checklist trước khi deploy
- Token ký bằng RS256/ES256, private key chỉ ở authorization server; JWKS có
kidvà kế hoạch xoay key. issuer-urivàaudiencesđược cấu hình; có test cho token sai issuer/audience.SessionCreationPolicy.STATELESS, không cóHttpSession, không có filter JWT tự viết.- Access token 5–15 phút; refresh token có rotation và phát hiện reuse; chiến lược thu hồi đã được chọn.
- Converter map đúng tiền tố
ROLE_, có unit test cho cảscopevàroles. - Không log token, không đặt PII trong payload, ép HTTPS ở ingress.
Trong series: Spring Security 101 để nắm xác thực và phân quyền, rồi bài RBAC ở trên để đi tiếp. Toàn bộ lộ trình nằm ở Spring Boot Roadmap 2026.



