Bạn thêm spring-boot-starter-security vào dự án, mở trình duyệt và nhận một màn hình đăng nhập do Spring tự sinh. API vừa viết trả 401 cho Postman, còn trang quản trị vẫn mở với một tài khoản người dùng thường. Đó là hai câu hỏi khác nhau: bạn là ai, và bạn được phép làm gì.
Bài này tách hai khái niệm, rồi lần theo request qua filter chain để thấy Spring Security trả lời từng câu ở đâu. Code dùng Security 7.1.2 trên Boot 4.1.2, Java 25 LTS.
Mục lục
Cập nhật 2026
- Lambda DSL là cách duy nhất.
and()đã bị bỏ từ Security 7,WebSecurityConfigurerAdapterbiến mất từ Security 6. Hướng dẫn cũ dùng hai thứ này không còn biên dịch. - URL authorization dùng
authorizeHttpRequestsvàrequestMatchers.authorizeRequestsvàantMatchersthuộc API cũ. - CSRF vẫn bật mặc định, và là nguồn 403 phổ biến nhất khi viết API.
- Passkey/WebAuthn đã có hỗ trợ nhưng API còn tiến hóa: đăng nhập không mật khẩu là thật, nhưng hợp đồng cấu hình có thể đổi, nên coi là PoC.
Hai câu hỏi, hai mã lỗi
Xác thực trả lời “bạn là ai”. Nó kiểm tra bằng chứng — mật khẩu, passkey, token — và gắn một danh tính vào request. Phân quyền trả lời “danh tính đó được làm gì”. Nó so quyền của danh tính với tài nguyên đang được yêu cầu.
Ví dụ: An đăng nhập thành công và gọi GET /api/orders/42. Request đã qua xác thực, nhưng đơn 42 thuộc về Bình, nên kết quả đúng là 403 Forbidden. Một request không có token hợp lệ nhận 401 Unauthorized: chưa chứng minh được danh tính.
Sai lầm phổ biến nhất là đọc .authenticated() thành “được phép”. Nó chỉ có nghĩa “phải đăng nhập”, và mọi tài khoản đã đăng nhập đều thỏa điều kiện đó.
| Khía cạnh | Xác thực | Phân quyền |
|---|---|---|
| Câu hỏi | Bạn là ai? | Bạn được làm gì? |
| Đầu vào | Mật khẩu, token, chứng chỉ | Danh tính và quyền của nó |
| Kết quả sai | 401 hoặc chuyển tới trang login | 403, hoặc 404 nếu muốn giấu tài nguyên |
| Thành phần | AuthenticationManager, UserDetailsService, PasswordEncoder |
AuthorizationFilter, AuthorizationManager, GrantedAuthority |
Request đi qua chuỗi filter nào
Servlet container chỉ biết filter springSecurityFilterChain qua DelegatingFilterProxy. Proxy chuyển vào bean FilterChainProxy, nơi chọn SecurityFilterChain đầu tiên khớp request. Mỗi chain giới hạn phạm vi bằng securityMatcher, nên có thể có chain cho web và chain riêng cho API.
Request -> DelegatingFilterProxy -> FilterChainProxy
-> SecurityFilterChain (chain dau tien khop)
-> UsernamePasswordAuthenticationFilter / BasicAuthenticationFilter
-> AuthenticationManager
-> AuthenticationProvider -> UserDetailsService + PasswordEncoder
-> SecurityContextHolderFilter (nap context, xoa khi request xong)
-> AuthorizationFilter (kiem tra quyen)
-> DispatcherServlet / Controller
AuthenticationFilter là tên chung cho filter lấy bằng chứng: UsernamePasswordAuthenticationFilter đọc form, BasicAuthenticationFilter đọc header Basic, BearerTokenAuthenticationFilter đọc bearer token. Filter tạo Authentication chưa xác thực rồi giao cho AuthenticationManager. Manager chọn một AuthenticationProvider; provider gọi UserDetailsService để tải người dùng và PasswordEncoder để so mật khẩu, rồi trả về Authentication đầy đủ principal và authorities.
Cuối chain, AuthorizationFilter đọc context và cho đi tiếp hay ném AccessDeniedException. Xác thực thất bại đi theo AuthenticationEntryPoint (401 hoặc redirect); phân quyền thất bại đi theo AccessDeniedHandler (403).
SecurityContextHolder và thread-local
Authentication sau khi xác thực được đặt vào SecurityContextHolder.getContext(); @PreAuthorize, AuthorizationFilter và code nghiệp vụ đọc danh tính từ đây. Holder mặc định dùng ThreadLocal, nên context gắn với thread đang xử lý request. SecurityContextHolderFilter nạp context đầu request và xóa khi request xong, để thread trong pool không mang danh tính người trước sang người sau.
Context không tự đi theo khi bạn đổi thread: @Async, ExecutorService, parallel stream hay CompletableFuture.supplyAsync đều chạy với context rỗng. Đừng đọc SecurityContextHolder ở đó rồi kết luận người dùng chưa đăng nhập.
Async và virtual thread
Cách sửa là bọc tác vụ bằng DelegatingSecurityContextRunnable, DelegatingSecurityContextCallable, DelegatingSecurityContextExecutor hoặc DelegatingSecurityContextAsyncTaskExecutor cho @Async. Cách khác đơn giản hơn là truyền principal hoặc user id như tham số thay vì phụ thuộc trạng thái ẩn.
Virtual thread không phá vỡ mô hình này, nhưng cũng không sửa nó: mỗi virtual thread có ThreadLocal riêng, và spring.threads.virtual.enabled=true chỉ đổi loại thread xử lý request, không lan context sang tác vụ bạn tự tách ra. MODE_INHERITABLETHREADLOCAL là di sản, chỉ lan sang thread con tạo trực tiếp và hay gây rò rỉ danh tính trong pool — đừng dùng. Java 25 đã có Scoped Values, nhưng Spring Security 7.1 vẫn dựa trên ThreadLocal; đừng giả định context tự theo structured concurrency.
UserDetailsService và PasswordEncoder
UserDetailsService là cầu nối giữa Spring Security và kho người dùng của bạn. Nó nhận username và trả UserDetails gồm mật khẩu đã mã hóa, trạng thái khóa và authorities. PasswordEncoder mã hóa khi đăng ký và so khớp khi đăng nhập; không lưu mật khẩu thô và không so sánh bằng equals.
// File: src/main/java/com/example/shop/security/SecurityConfig.java
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
PasswordEncoder passwordEncoder() {
return PasswordEncoderFactories.createDelegatingPasswordEncoder();
}
@Bean
UserDetailsService userDetailsService(PasswordEncoder encoder) {
UserDetails an = User.withUsername("an@shop.vn")
.password(encoder.encode("mat-khau-demo"))
.roles("USER")
.build();
UserDetails admin = User.withUsername("admin@shop.vn")
.password(encoder.encode("mat-khau-admin"))
.roles("ADMIN", "USER")
.build();
return new InMemoryUserDetailsManager(an, admin);
}
}
roles("ADMIN") ghi ra authority ROLE_ADMIN, không phải chuỗi ADMIN. createDelegatingPasswordEncoder() mặc định dùng bcrypt và gắn tiền tố {bcrypt} vào hash, nhờ đó bạn xác minh được hash cũ trong lúc di trú. Khi có bean UserDetailsService và PasswordEncoder, Boot tự cấu hình DaoAuthenticationProvider; ứng dụng thật thay InMemoryUserDetailsManager bằng implementation đọc từ repository.
Session hay JWT: chọn theo client
Mặc định của Spring Security là session: sau khi đăng nhập, server tạo JSESSIONID trong cookie HttpOnly, danh tính nằm phía server. Cách này phù hợp web render phía server và thu hồi quyền tức thì bằng cách xóa session. JWT stateless đặt danh tính trong token do client giữ; server chỉ kiểm tra chữ ký. Token không thu hồi được nếu thiếu denylist, token version hoặc thời hạn ngắn.
| Tiêu chí | Session (cookie) | JWT stateless |
|---|---|---|
| Trạng thái | Server giữ session | Client giữ token, server xác minh |
| Thu hồi | Xóa session là xong | Cần denylist hoặc token version |
| CSRF | Cần bảo vệ vì cookie tự gửi | Tắt được nếu token đi qua header |
| Phù hợp | Web same-site, form login | Mobile, SPA gọi API, service-to-service |
Với web một domain, session cộng cookie SameSite=Lax đơn giản và an toàn hơn JWT. Với API nhiều client, token ngắn hạn cộng refresh token là mô hình đúng; đừng nhét dữ liệu nhạy cảm vào payload vì JWT chỉ được ký, không được mã hóa.
CSRF và CORS không thay thế nhau
CSRF lợi dụng việc trình duyệt tự đính cookie vào request gửi tới đúng domain. Nếu ứng dụng xác thực bằng cookie session, kẻ tấn công có thể dụ người dùng gửi POST đổi mật khẩu. Token CSRF chứng minh form đến từ chính trang của bạn. Vì vậy CSRF áp dụng khi trạng thái đăng nhập đi qua cookie, gồm cả JWT đặt trong cookie.
Tắt CSRF khi client không dùng cookie để xác thực: API nhận Authorization: Bearer ..., mobile app, service-to-service. Trình duyệt không tự gắn header đó, nên không có ambient credential để lợi dụng. Với SPA dùng cookie session, đừng tắt; dùng CookieCsrfTokenRepository.withHttpOnlyFalse() để JavaScript đọc cookie XSRF-TOKEN và gửi lại header X-XSRF-TOKEN.
http.csrf(csrf -> csrf
.csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse()));
CORS là cơ chế trình duyệt quyết định JavaScript từ origin khác có được đọc response hay không. CORS không chặn request được gửi đi — form POST cross-site vẫn tới server — nên nó không phải biện pháp chống CSRF. CORS bảo vệ dữ liệu trả về khỏi origin lạ; CSRF bảo vệ thay đổi trạng thái khỏi request mượn danh người dùng.
Mặc định của Spring Boot: mọi endpoint đều bị chặn
Chỉ cần starter trên classpath, SecurityAutoConfiguration bật một chain mặc định: mọi request cần xác thực, form login và HTTP Basic cùng bật, Boot in ra console dòng Using generated security password: với user tên user. Đây là lý do Postman nhận 401 và trình duyệt nhảy tới trang login ngay sau khi thêm dependency.
Hai lần “back off” đáng nhớ: khai báo bean SecurityFilterChain thay toàn bộ chain mặc định; khai báo bean UserDetailsService bỏ user sinh tự động. Với Actuator, chain mặc định cho phép /actuator/health và chặn phần còn lại. Khi bạn tự khai báo chain, cơ chế đó biến mất — nếu không permit health, probe Kubernetes nhận 401 và pod bị restart.
Cấu hình 1: ứng dụng web với form login
// File: src/main/java/com/example/shop/security/WebSecurityConfig.java
@Bean
SecurityFilterChain webChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/", "/css/**", "/js/**", "/login").permitAll()
.requestMatchers("/admin/**").hasRole("ADMIN")
.requestMatchers("/account/**").hasAnyRole("USER", "ADMIN")
.anyRequest().authenticated())
.formLogin(form -> form
.loginPage("/login")
.defaultSuccessUrl("/account", true)
.permitAll())
.logout(logout -> logout
.logoutUrl("/logout")
.logoutSuccessUrl("/login?logout")
.invalidateHttpSession(true)
.deleteCookies("JSESSIONID"));
return http.build();
}
Chain này giữ session và CSRF mặc định. Nhớ permitAll chính trang login, nếu không bạn tạo vòng lặp redirect. Với Thymeleaf, token CSRF được chèn tự động vào form có th:action; template tự viết phải render hidden input chứa token. defaultSuccessUrl("/account", true) buộc về trang cố định thay vì URL lưu trước khi login.
Cấu hình 2: API stateless với JWT
Với API, tách chain bằng securityMatcher, tắt session và CSRF, rồi để resource server xác minh JWT. Cách gọn nhất là dùng oauth2ResourceServer với identity provider phát token; nếu bạn tự phát và kiểm tra token, filter tùy chỉnh được trình bày trong bài JWT của series.
// File: src/main/java/com/example/shop/security/ApiSecurityConfig.java
@Bean
SecurityFilterChain apiChain(HttpSecurity http) throws Exception {
http
.securityMatcher("/api/**")
.authorizeHttpRequests(auth -> auth
.requestMatchers("/api/public/**").permitAll()
.requestMatchers(HttpMethod.GET, "/api/products/**").permitAll()
.requestMatchers("/api/admin/**").hasRole("ADMIN")
.anyRequest().authenticated())
.sessionManagement(sm -> sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.csrf(csrf -> csrf.disable())
.oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
return http.build();
}
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://auth.example.com/realms/shop
Với token do provider phát, authority của scope có tiền tố SCOPE_, nên kiểm tra bằng hasAuthority("SCOPE_orders:read"). Nếu có nhiều chain, chain không đặt securityMatcher sẽ khớp mọi request; đặt nó cuối bằng @Order, vì FilterChainProxy chọn chain khớp đầu tiên.
Đọc đúng authorizeHttpRequests và requestMatchers
authorizeHttpRequests nhận một AuthorizationManager cho từng nhóm request. Quy tắc đánh giá theo thứ tự khai báo và dừng ở match đầu tiên, không có “quy tắc cụ thể hơn thắng tự động”. Đặt /api/admin/** trước /api/**; luôn kết thúc bằng anyRequest().
requestMatchers nhận pattern MVC (khi có Spring MVC) hoặc Ant/Servlet, và có overload nhận HttpMethod. permitAll() không “bỏ qua mọi filter”: request vẫn qua chain, chỉ không cần danh tính. anonymous() chỉ cho người chưa đăng nhập; denyAll() chặn tuyệt đối.
Tiền tố role là chỗ dễ sai nhất. hasRole("ADMIN") tự thêm ROLE_ và so với ROLE_ADMIN; hasAuthority("ROLE_ADMIN") so đúng chuỗi đó. Viết hasRole("ROLE_ADMIN") sẽ tìm ROLE_ROLE_ADMIN và luôn từ chối — lỗi im lặng. Role cũng không có thứ bậc: ADMIN không tự động có quyền USER trừ khi cấu hình RoleHierarchy.
Quy tắc URL mô tả tài nguyên, không mô tả chủ sở hữu. “Chỉ ADMIN xem báo cáo” là việc của hasRole; “chỉ An xem đơn 42” phải kiểm trong service hoặc bằng method security kiểu @PreAuthorize("@orderService.canAccess(#id)").
Những lỗi người mới gặp nhiều nhất
Tắt CSRF cho ứng dụng dùng cookie session. Đây là lỗ hổng thật, không phải phiền toái cấu hình. POST trả 403 thường vì thiếu token trong form hoặc header; sửa đúng chỗ đó. Chỉ tắt khi xác thực đi qua bearer header và không có cookie mang danh tính.
PermitAll cả /actuator/**. Health không nhạy cảm, nhưng env, beans, heapdump thì có. Chỉ permit /actuator/health, hoặc đặt Actuator trên cổng quản trị riêng với role riêng.
Lưu mật khẩu thô. NoOpPasswordEncoder, {noop} hay cột password chứa chuỗi người dùng nhập đều là sự cố chờ xảy ra. Dùng delegating encoder ngay từ đầu; dữ liệu cũ thì mã hóa lại mỗi lần đăng nhập thành công.
Copy code của Boot 2. WebSecurityConfigurerAdapter và and() đã bị xóa; authorizeRequests và antMatchers thuộc API cũ. IDE báo không tìm thấy method thì viết lại theo lambda DSL, đừng thêm dependency cũ.
Hiểu “authenticated” là “authorized”. .anyRequest().authenticated() chỉ chặn khách; mọi user đã đăng nhập vẫn vào được URL không có quy tắc riêng. Luôn có quy tắc role hoặc kiểm tra sở hữu cho tài nguyên nhạy cảm.
Quên rằng authority đến từ dữ liệu. Quyền nằm trong UserDetails bạn trả về, không nằm trong URL hay annotation. Database gán sai role thì hasRole trả lời đúng theo dữ liệu sai.
Nhìn tới 2027
Passkey/WebAuthn đang thành lựa chọn thay mật khẩu, và Spring Security đã có nền tảng cho relying party; API vẫn đang hoàn thiện nên hãy thử nghiệm trước khi đưa vào lộ trình bắt buộc. Security 7.2.0-RC1 và Boot 4.2.0-RC2 đang là preview. Hướng đi vẫn là lambda DSL, authorization theo method và nhiều lớp phòng thủ, thay vì một cấu hình URL duy nhất.
Checklist trước khi commit
- Mỗi endpoint có quy tắc: permitAll, role nào, hay chỉ cần đăng nhập.
- Không có
/actuator/**hay/admin/**rơi vàopermitAll. - Mật khẩu lưu dạng hash có tiền tố; không còn
{noop}. - Biết ứng dụng dùng session hay token, và CSRF bật/tắt có lý do.
- Không đọc
SecurityContextHoldertrong thread tự tạo khi chưa bọc delegate. - Có test cho 401 và 403.
Bước tiếp theo trong series là cấu hình xác thực thực tế với database trong Hướng dẫn thực hành cấu hình xác thực trong Spring, rồi mở rộng sang Role-Based Access Control. Khi cần token cho API, đọc JWT Authentication trong Spring Boot; khi cần đăng nhập bằng bên thứ ba, xem OAuth2 với Spring Security.



