Form login hiện ra không có nghĩa là cấu hình xác thực đã đúng. Mặc định của Spring Security bảo vệ mọi URL, sinh một user với mật khẩu ngẫu nhiên lúc khởi động và bật CSRF — ba thứ đó va vào nhau ngay khi bạn thêm trang đăng nhập riêng. Bài này dựng một project chạy được trên Spring Security 7.1.2 / Spring Boot 4.1.2: user nằm trong database qua JPA, mật khẩu BCrypt, remember-me, kiểm soát session, và test cho cả trang lẫn luồng đăng nhập thật.
Mục lục
Cập nhật 2026
- Spring Security 7.1.2 trên Boot 4.1.2 / Framework 7.0.10.
WebSecurityConfigurerAdapterđã bị xóa từ Security 6; trong 7.0authorizeRequests(),and()vàcsrf()không tham số cũng không còn — chỉ viết lambda DSL. DaoAuthenticationProviderchỉ còn constructor nhậnUserDetailsService; cách cũnew DaoAuthenticationProvider()rồisetUserDetailsService(...)không dùng được nữa.- Boot 4.1 đánh dấu
spring-boot-starter-weblà deprecated; dùngspring-boot-starter-webmvccho code mới. - Mật khẩu nên là Argon2id hoặc BCrypt với cost đủ cao. Passkey/WebAuthn đã có trong hệ sinh thái Security nhưng là lựa chọn bổ sung, không bắt buộc.
Cấu hình xác thực trong Spring: một lần đăng nhập đi qua đâu?
Spring Security là một chuỗi filter trong servlet container. Với form login, UsernamePasswordAuthenticationFilter đọc hai field username/password, tạo UsernamePasswordAuthenticationToken chưa xác thực rồi giao cho AuthenticationManager. Manager chọn một AuthenticationProvider — mặc định là DaoAuthenticationProvider. Provider gọi UserDetailsService.loadUserByUsername() để lấy UserDetails, rồi so khớp bằng PasswordEncoder.matches(raw, stored).
Thành công thì SecurityContext được lưu vào session (mặc định), và SessionAuthenticationStrategy đổi session id trước khi ghi context. Thất bại thì filter chuyển hướng tới failureUrl với một thông báo chung. Bốn mắt xích — filter, provider, UserDetailsService, encoder — là toàn bộ những gì bạn phải cấu hình; sai một mắt xích, biểu hiện luôn giống nhau: “đăng nhập không được”.
Dựng project: dependency, entity, repository
Project demo dùng Java 25, Gradle 9.9, package vn.evotek.auth, với dependency đầy đủ gồm cả test:
// File: build.gradle (phần dependency)
implementation 'org.springframework.boot:spring-boot-starter-webmvc'
implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
runtimeOnly 'org.postgresql:postgresql'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
testImplementation 'org.springframework.security:spring-security-test'
testImplementation 'org.springframework.boot:spring-boot-testcontainers'
testImplementation 'org.testcontainers:testcontainers-postgresql'
testImplementation 'org.testcontainers:testcontainers-junit-jupiter'
Entity giữ đúng ba thứ Spring Security cần: định danh duy nhất, hash mật khẩu, và danh sách quyền. Cột passwordHash không bao giờ chứa mật khẩu thô, và enabled cho phép bạn khóa tài khoản mà không xóa dữ liệu.
// File: src/main/java/vn/evotek/auth/AppUser.java
@Entity
@Table(name = "app_users")
public class AppUser {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, unique = true, length = 64)
private String username;
@Column(nullable = false, length = 100)
private String passwordHash;
@Column(nullable = false)
private boolean enabled = true;
@ElementCollection(fetch = FetchType.EAGER)
@CollectionTable(name = "app_user_roles",
joinColumns = @JoinColumn(name = "user_id"))
@Column(name = "role", length = 32)
private Set<String> roles = new HashSet<>();
protected AppUser() { }
// getters/setters
}
// File: src/main/java/vn/evotek/auth/AppUserRepository.java
public interface AppUserRepository extends JpaRepository<AppUser, Long> {
Optional<AppUser> findByUsername(String username);
}
Username nên được trim và lower-case ngay ở tầng đăng ký: findByUsername so sánh chính xác từng ký tự, còn collation của Postgres thì thay đổi theo cấu hình database.
UserDetailsService đọc user từ JPA
Đây là nơi duy nhất bạn chạm database trong luồng xác thực. Trả về User của Spring thay vì trả entity: User đã cài equals/hashCode đúng — điều kiện để session registry theo dõi phiên — và bạn không vô tình đưa entity ra ngoài transaction.
// File: src/main/java/vn/evotek/auth/AppUserDetailsService.java
@Service
public class AppUserDetailsService implements UserDetailsService {
private final AppUserRepository users;
public AppUserDetailsService(AppUserRepository users) {
this.users = users;
}
@Override
@Transactional(readOnly = true)
public UserDetails loadUserByUsername(String username) {
AppUser user = users.findByUsername(username)
.orElseThrow(() -> new UsernameNotFoundException("Bad credentials"));
return User.withUsername(user.getUsername())
.password(user.getPasswordHash())
.disabled(!user.isEnabled())
.authorities(user.getRoles().stream()
.map(role -> new SimpleGrantedAuthority("ROLE_" + role))
.toList())
.build();
}
}
@Transactional(readOnly = true) giữ session mở đủ để collection roles được nạp và không mở đường ghi ngoài ý muốn. Quy ước ROLE_ là bắt buộc nếu bạn dùng hasRole("ADMIN"): hasRole tự thêm tiền tố, còn hasAuthority("ADMIN") thì không.
SecurityFilterChain: cấu hình đầy đủ
Với Boot, @EnableWebSecurity không bắt buộc; một bean SecurityFilterChain là đủ để thay toàn bộ mặc định. Cấu hình dưới đây bật form login, logout, remember-me, session fixation và giới hạn một phiên mỗi user.
// File: src/main/java/vn/evotek/auth/SecurityConfig.java
@Configuration
public class SecurityConfig {
@Value("${app.security.remember-me-key:dev-only-change-me}")
private String rememberMeKey;
@Bean
SecurityFilterChain filterChain(HttpSecurity http,
AuthenticationProvider provider,
AppUserDetailsService users) throws Exception {
http
.authenticationProvider(provider)
.authorizeHttpRequests(auth -> auth
.requestMatchers("/login", "/css/**", "/error").permitAll()
.requestMatchers("/admin/**").hasRole("ADMIN")
.anyRequest().authenticated())
.formLogin(form -> form
.loginPage("/login")
.loginProcessingUrl("/login")
.defaultSuccessUrl("/", false)
.failureUrl("/login?error")
.permitAll())
.logout(out -> out
.logoutUrl("/logout")
.logoutSuccessUrl("/login?logout")
.invalidateHttpSession(true)
.clearAuthentication(true)
.deleteCookies("JSESSIONID")
.permitAll())
.rememberMe(rm -> rm
.key(rememberMeKey)
.tokenValiditySeconds(14 * 24 * 60 * 60)
.userDetailsService(users))
.sessionManagement(session -> session
.sessionFixation(fix -> fix.changeSessionId())
.maximumSessions(1)
.maxSessionsPreventsLogin(false)
.expiredUrl("/login?expired"));
return http.build();
}
@Bean
AuthenticationProvider authenticationProvider(AppUserDetailsService users,
PasswordEncoder encoder) {
DaoAuthenticationProvider provider = new DaoAuthenticationProvider(users);
provider.setPasswordEncoder(encoder);
return provider;
}
@Bean
PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder(12);
}
@Bean
HttpSessionEventPublisher httpSessionEventPublisher() {
return new HttpSessionEventPublisher();
}
}
Vài điểm dễ đọc sai. requestMatchers được xét theo thứ tự khai báo, nên rule cụ thể phải đứng trước anyRequest(). csrf không được tắt ở đây: form login cần token, và mọi POST khác cũng cần. defaultSuccessUrl("/", false) tôn trọng URL người dùng định vào trước khi bị chặn. Bean AuthenticationProvider duy nhất được dùng làm provider toàn cục, nên đừng khai báo UserDetailsService hai lần.
Trang đăng nhập tùy chỉnh
loginPage("/login") chỉ đổi trang hiển thị; POST vẫn do filter xử lý. Bạn cần một controller cho GET và không được map POST cùng đường dẫn. Tên input phải đúng username/password, còn checkbox remember-me dùng đúng tên tham số mặc định remember-me.
<!-- File: src/main/resources/templates/login.html -->
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org" lang="vi">
<head><meta charset="UTF-8"><title>Đăng nhập</title></head>
<body>
<div th:if="${param.error}">Tên đăng nhập hoặc mật khẩu không đúng.</div>
<div th:if="${param.logout}">Bạn đã đăng xuất.</div>
<div th:if="${param.expired}">Tài khoản đã đăng nhập ở nơi khác.</div>
<form th:action="@{/login}" method="post">
<label for="username">Tên đăng nhập</label>
<input id="username" name="username" type="text" required autofocus>
<label for="password">Mật khẩu</label>
<input id="password" name="password" type="password" required>
<input id="remember-me" name="remember-me" type="checkbox">
<label for="remember-me">Ghi nhớ đăng nhập 14 ngày</label>
<button type="submit">Đăng nhập</button>
</form>
</body>
</html>
// File: src/main/java/vn/evotek/auth/LoginController.java
@Controller
public class LoginController {
@GetMapping("/login")
String login() {
return "login";
}
}
th:action không chỉ tạo URL: nó đi qua RequestDataValueProcessor của Spring và tự chèn hidden _csrf. Nếu bạn viết <form action="/login"> bằng HTML thuần, token biến mất và lần submit nào cũng nhận 403 — lỗi này xuất hiện đúng lúc bạn vừa “đơn giản hóa” template.
Mật khẩu: BCrypt, Argon2id và cost
BCryptPasswordEncoder(12) là lựa chọn an toàn, quen thuộc: salt tự sinh, cost 12 tương đương 4096 vòng băm. Hãy đo trên phần cứng thật và chọn cost sao cho một lần hash mất khoảng 100–250 ms; cost 10 quá nhẹ cho năm 2026.
Argon2id chống tấn công bằng GPU tốt hơn vì tốn cả RAM lẫn CPU. Spring có Argon2PasswordEncoder (cần BouncyCastle trên classpath), khởi tạo bằng defaultsForSpringSecurity_v5_8() hoặc constructor new Argon2PasswordEncoder(16, 32, 1, 1 << 14, 2). Điều quan trọng không phải thuật toán bạn chọn mà là encode một lần lúc ghi và chỉ matches lúc đọc. Nếu bạn dùng PasswordEncoderFactories.createDelegatingPasswordEncoder(), hash lưu kèm prefix {bcrypt} và việc đổi thuật toán sau này chỉ là thêm encoder mới, không cần migrate hàng loạt.
Remember-me, logout và session
Remember-me mặc định là hash token ký bằng key, gắn với username trong cookie remember-me. Mỗi request có cookie sẽ gọi lại UserDetailsService, nên tài khoản bị khóa vẫn bị chặn dù token còn hạn. key phải ổn định giữa các instance và được giữ kín; đổi key giữa chừng sẽ vô hiệu hóa toàn bộ token. Để thu hồi từng token, dùng PersistentTokenRepository (bảng persistent_logins).
Logout phải là POST có CSRF, hủy session, xóa authentication và xóa cookie JSESSIONID; đặt logoutUrl trùng với form trong template. Session fixation: mặc định trên servlet 3.1+ là changeSessionId — giữ nguyên session, chỉ đổi id sau khi đăng nhập. Đừng đặt none để “cho nhanh”; đó là bỏ luôn lớp chống đánh cắp session id.
Với maximumSessions(1), maxSessionsPreventsLogin(false) cho phép phiên mới đăng nhập và đẩy phiên cũ ra, người bị đẩy nhận /login?expired. Cần bean HttpSessionEventPublisher như trên để registry nhận sự kiện session bị hủy; thiếu nó, bộ đếm không giảm và lần đăng nhập sau bị chặn sai. Nếu chạy nhiều instance sau load balancer, registry in-memory không đủ — phải dùng Spring Session với backing store chia sẻ.
Kiểm thử: MockMvc và luồng thật với Testcontainers
@WebMvcTest cắt context nên SecurityConfig không được scan; import nó và mock UserDetailsService để test rule và view. @WithMockUser đặt sẵn authentication, bỏ qua provider và database — phù hợp để test phân quyền, không phù hợp để test mật khẩu.
// File: src/test/java/vn/evotek/auth/LoginPageTest.java
@WebMvcTest(LoginController.class)
@Import(SecurityConfig.class)
class LoginPageTest {
@Autowired MockMvc mvc;
@MockitoBean AppUserDetailsService users;
@Test
void trangDangNhapLuonCongKhai() throws Exception {
mvc.perform(get("/login"))
.andExpect(status().isOk())
.andExpect(view().name("login"));
}
@Test
void khachBiChuyenHuongVaoLogin() throws Exception {
mvc.perform(get("/"))
.andExpect(status().is3xxRedirection())
.andExpect(redirectedUrlPattern("**/login"));
}
@Test
@WithMockUser(username = "alice", roles = "USER")
void userThuongKhongVaoDuocAdmin() throws Exception {
mvc.perform(get("/admin"))
.andExpect(status().isForbidden());
}
}
Test tích hợp dùng database thật qua Testcontainers để kiểm tra đúng thứ mà unit test bỏ qua: đọc user từ bảng, so khớp BCrypt, và chuyển hướng sau khi đăng nhập. formLogin() của spring-security-test tự kèm CSRF token, còn post("/login") thì không.
// File: src/test/java/vn/evotek/auth/LoginFlowIT.java
@SpringBootTest
@AutoConfigureMockMvc
@Testcontainers
@TestPropertySource(properties = "spring.jpa.hibernate.ddl-auto=create-drop")
class LoginFlowIT {
@Container
@ServiceConnection
static PostgreSQLContainer<?> postgres =
new PostgreSQLContainer<>("postgres:17-alpine");
@Autowired MockMvc mvc;
@Autowired AppUserRepository users;
@Autowired PasswordEncoder encoder;
@BeforeEach
void seed() {
users.deleteAll();
AppUser user = new AppUser();
user.setUsername("demo");
user.setPasswordHash(encoder.encode("demo1234"));
user.setRoles(Set.of("USER"));
users.save(user);
}
@Test
void dangNhapThanhCong() throws Exception {
mvc.perform(formLogin("/login").user("demo").password("demo1234"))
.andExpect(authenticated().withUsername("demo"))
.andExpect(redirectedUrl("/"));
}
@Test
void saiMatKhauQuayLaiTrangLogin() throws Exception {
mvc.perform(formLogin("/login").user("demo").password("sai"))
.andExpect(unauthenticated())
.andExpect(redirectedUrl("/login?error"));
}
}
Testcontainers không phải database nhúng, nên Boot không tự đặt ddl-auto; create-drop trong @TestPropertySource là bắt buộc nếu bạn chưa có Flyway. Cũng đừng quên spring-security-test ở scope test — thiếu nó, @WithMockUser và các matcher authenticated() không tồn tại.
Sai lầm thường gặp
Mật khẩu thô và prefix {noop}
DelegatingPasswordEncoder chọn encoder theo prefix trong chuỗi hash. Một row kiểu {noop}secret được so sánh plaintext và vẫn “đăng nhập được”, nên dữ liệu seed cũ hoặc script migrate có thể vô tình mở toàn bộ tài khoản. Hãy kiểm tra mọi giá trị không bắt đầu bằng {bcrypt} (hoặc {argon2} nếu đã đăng ký encoder đó) và mã hóa lại trước khi chuyển production.
Băm lại mật khẩu mỗi lần load user
Nếu loadUserByUsername gọi passwordEncoder.encode(...), mỗi request tốn thêm một lần băm và hash trong DB không bao giờ khớp giá trị vừa sinh. Encoder chỉ dùng ở luồng ghi (đăng ký, đổi mật khẩu); luồng đọc chỉ gọi matches(). Muốn nâng cost mà không bắt user đổi mật khẩu, dùng UserDetailsPasswordService để provider tự cập nhật khi phát hiện hash cũ.
Lộ user qua thông báo lỗi
Thông báo “không có tài khoản” và “sai mật khẩu” khác nhau biến form login thành công cụ dò username. Giữ một câu chung cho mọi trường hợp thất bại; hideUserNotFoundExceptions mặc định là true nên UsernameNotFoundException đã được đổi thành lỗi xác thực, nhưng custom AuthenticationFailureHandler có thể vô tình bỏ bảo vệ này. Form đăng ký cũng rò rỉ nếu trả “username đã tồn tại”.
Thiếu CSRF token trong form tự viết
Form HTML thuần không có hidden _csrf sẽ nhận 403 dù mật khẩu đúng. Dùng th:action, hoặc thêm thủ công input với ${_csrf.parameterName} và ${_csrf.token}. Với client JavaScript, gửi token qua header thay vì tắt CSRF; csrf(c -> c.disable()) chỉ hợp lý cho API stateless dùng token riêng.
Vòng lặp chuyển hướng vì thiếu permitAll
Nếu /login không nằm trong permitAll(), người chưa đăng nhập bị đẩy về /login, rồi chính trang đó lại yêu cầu đăng nhập — trình duyệt báo “too many redirects”. CSS/JS và trang /error bị chặn gây ra vòng lặp hoặc lỗi khó đọc tương tự; kiểm tra cả ba nhóm URL trước khi đổ lỗi cho filter.
Hai bean UserDetailsService
Đặt @Service lên class và đồng thời khai báo @Bean UserDetailsService userDetailsService() tạo hai bean cùng type. Boot lùi cấu hình mặc định, còn Spring Security chỉ tự chọn provider khi có đúng một bean — kết quả là không có provider phù hợp, mọi lần đăng nhập đều thất bại. Chọn một nguồn duy nhất; nếu buộc phải có hai, đánh dấu @Primary và chỉ định provider tường minh.
Checklist trước khi deploy
- Cột mật khẩu chỉ chứa hash có prefix; không còn row
{noop}hay plaintext. /login, static resources và/errorđềupermitAll(); CSRF vẫn bật.- Cost BCrypt (hoặc tham số Argon2) đã đo trên hardware thật, không dùng mặc định 10 mà không suy nghĩ.
- Remember-me key lấy từ secret manager, giống nhau trên mọi instance.
- Có test 403 cho user thường vào
/admin, test đăng nhập đúng và sai với database thật. - Logout là POST, hủy session và xóa cookie; session fixation để
changeSessionId.
Nhìn sang 2027
Spring Security 7.2.0-RC1 đang ở dạng preview, chưa GA; các API cốt lõi trong bài — SecurityFilterChain, UserDetailsService, DaoAuthenticationProvider — không đổi. Passkey/WebAuthn sẽ dần phổ biến như yếu tố thứ hai bên cạnh mật khẩu, nhưng chưa thay thế form login trong phần lớn hệ thống nội bộ. Với mật khẩu, hãy chuẩn bị sẵn đường nâng cấp lên Argon2id thay vì chờ phải migrate.
Bài tiếp theo
- Spring Security 101: Xác thực vs Phân quyền — nền tảng khái niệm của bài này.
- Triển khai Role-Based Access Control — từ
hasRoleđến cấu hình quyền theo bảng. - JWT Authentication trong Spring Boot — khi bạn cần API stateless thay vì session.
- Spring Boot Roadmap 2026 — vị trí bài này trong lộ trình.



