Bạn viết hasRole("ROLE_ADMIN") và nhận 403, dù trong database role tên là ADMIN và code đã thêm tiền tố. Role-Based Access Control (RBAC) trong Spring Security không phải một tính năng bật lên là xong: nó chỉ là quy ước đặt chuỗi GrantedAuthority. Quy ước tiền tố, cấp chặn và giới hạn của RBAC quyết định hệ phân quyền của bạn đúng hay chỉ trông đúng.
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. Mọi thứ là
jakarta.*; JSR-250 dùngjakarta.annotation.security.RolesAllowed, không cònjavax. requestMatchers("/admin/**")so khớp bằngPathPatternRequestMatchertheoPathPatterncủa Spring MVC, không phải Ant matcher:**chỉ hợp lệ ở cuối pattern, nên/admin/**/editkhông parse được.@EnableMethodSecuritylà công tắc duy nhất:prePostEnabled=truemặc định, cònsecuredEnabled=falsevàjsr250Enabled=false.@Securedvà@RolesAllowedkhông tự hoạt động.WebSecurityConfigurerAdapterđã bị xóa từ Security 6. Luật URL chạy quaAuthorizationManager, không cònAccessDecisionManagervà voter.
Role-Based Access Control: users → roles → permissions
RBAC gán quyền cho vai trò, rồi gán vai trò cho người dùng: sửa một role, mọi người mang role đó nhận thay đổi. Mô hình tối thiểu cần năm bảng:
-- PostgreSQL 17+
create table users (
id bigint generated by default as identity primary key,
username varchar(64) not null unique,
password_hash varchar(100) not null,
enabled boolean not null default true
);
create table roles (
id bigint generated by default as identity primary key,
name varchar(40) not null unique -- ADMIN, MANAGER, USER: tên trần, không có ROLE_
);
create table permissions (
id bigint generated by default as identity primary key,
code varchar(80) not null unique -- orders:read, orders:write, invoices:export
);
create table user_roles (
user_id bigint not null references users(id) on delete cascade,
role_id bigint not null references roles(id) on delete restrict,
primary key (user_id, role_id)
);
create table role_permissions (
role_id bigint not null references roles(id) on delete cascade,
permission_id bigint not null references permissions(id) on delete restrict,
primary key (role_id, permission_id)
);
Một người có nhiều role, một role có nhiều permission. Đừng nén permission thành cột text trong roles: sẽ không join, không đếm, không thu hồi được.
| Dữ liệu | Authority sinh ra | Kiểm tra bằng |
|---|---|---|
roles.name = 'ADMIN' |
ROLE_ADMIN |
hasRole("ADMIN") hoặc hasAuthority("ROLE_ADMIN") |
permissions.code = 'orders:read' |
orders:read |
hasAuthority("orders:read") |
Role là quy ước, authority là dữ liệu
GrantedAuthority chỉ có một method getAuthority() trả về String. Ở runtime Spring Security so chuỗi, không có cờ nào đánh dấu “đây là role”. Role chỉ là authority có tiền tố; permission là authority không có tiền tố. hasRole("ADMIN") thực chất là hasAuthority("ROLE_" + "ADMIN"), với tiền tố lấy từ bean GrantedAuthorityDefaults (mặc định ROLE_). Bean này được cả luật URL và method security đọc, nên đổi một chỗ là đổi toàn hệ.
| Bạn viết | Chuỗi Spring tìm | Với authority ROLE_ADMIN |
|---|---|---|
hasRole("ADMIN") |
ROLE_ADMIN |
Cho qua |
hasRole("ROLE_ADMIN") |
ROLE_ROLE_ADMIN |
403 |
hasAuthority("ADMIN") |
ADMIN |
403 |
hasAuthority("ROLE_ADMIN") |
ROLE_ADMIN |
Cho qua |
Tiền tố kép có hai đường vào: database lưu tên trần nhưng ai đó viết hasRole("ROLE_ADMIN"), hoặc database lưu sẵn ROLE_ADMIN và mapper thêm lần nữa. Cả hai cho ra ROLE_ROLE_ADMIN. Cách chữa là chọn một biên: database lưu tên trần, đúng một chỗ thêm tiền tố.
UserDetailsService: nạp role và permission thành authority
Authority được nạp một lần khi đăng nhập và gắn vào Authentication — điểm duy nhất bạn kiểm soát chuỗi nào đi vào hệ, nên cũng là điểm nên test.
// File: src/main/java/com/evotek/shop/security/UserAccount.java
// imports: jakarta.persistence.*, java.util.*
@Entity
@Table(name = "users")
public class UserAccount {
@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, unique = true, length = 64)
private String username;
@Column(name = "password_hash", nullable = false, length = 100)
private String passwordHash;
@Column(nullable = false)
private boolean enabled = true;
@ManyToMany(fetch = FetchType.LAZY)
@JoinTable(name = "user_roles",
joinColumns = @JoinColumn(name = "user_id"),
inverseJoinColumns = @JoinColumn(name = "role_id"))
private Set<Role> roles = new HashSet<>();
// getters
}
@Entity
@Table(name = "roles")
public class Role {
@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, unique = true, length = 40)
private String name; // "ADMIN", không phải "ROLE_ADMIN"
@ManyToMany(fetch = FetchType.LAZY)
@JoinTable(name = "role_permissions",
joinColumns = @JoinColumn(name = "role_id"),
inverseJoinColumns = @JoinColumn(name = "permission_id"))
private Set<Permission> permissions = new HashSet<>();
// getters
}
@Entity
@Table(name = "permissions")
public class Permission {
@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false, unique = true, length = 80)
private String code; // "orders:read"
// getter
}
// File: src/main/java/com/evotek/shop/security/UserAccountRepository.java
// imports: org.springframework.data.jpa.repository.*, java.util.Optional
public interface UserAccountRepository extends JpaRepository<UserAccount, Long> {
@EntityGraph(attributePaths = { "roles", "roles.permissions" })
Optional<UserAccount> findByUsername(String username);
}
// File: src/main/java/com/evotek/shop/security/AppUserDetailsService.java
// imports: org.springframework.security.core.GrantedAuthority,
// org.springframework.security.core.authority.SimpleGrantedAuthority,
// org.springframework.security.core.userdetails.*,
// org.springframework.stereotype.Service,
// org.springframework.transaction.annotation.Transactional,
// java.util.List, java.util.stream.Stream
@Service
public class AppUserDetailsService implements UserDetailsService {
private static final String ROLE_PREFIX = "ROLE_";
private final UserAccountRepository users;
public AppUserDetailsService(UserAccountRepository users) {
this.users = users;
}
@Override
@Transactional(readOnly = true)
public UserDetails loadUserByUsername(String username) {
UserAccount account = this.users.findByUsername(username)
.orElseThrow(() -> new UsernameNotFoundException("Không có user: " + username));
List<GrantedAuthority> authorities = account.getRoles().stream()
.flatMap(role -> Stream.<GrantedAuthority>concat(
Stream.of(new SimpleGrantedAuthority(ROLE_PREFIX + role.getName())),
role.getPermissions().stream()
.map(permission -> new SimpleGrantedAuthority(permission.getCode()))))
.toList();
return User.withUsername(account.getUsername())
.password(account.getPasswordHash())
.authorities(authorities)
.disabled(!account.isEnabled())
.build();
}
}
@EntityGraph kéo roles và roles.permissions trong một query, tránh LazyInitializationException. Authority trùng giữa hai role không gây hại. Mật khẩu phải là hash do PasswordEncoder tạo. Có đúng một bean UserDetailsService và một PasswordEncoder, Spring Security tự dựng DaoAuthenticationProvider.
Chặn ở cấp URL với authorizeHttpRequests
Luật URL là lớp lọc thô: bảo vệ cả một vùng, không biết dữ liệu bên trong thuộc ai. Viết từ cụ thể đến tổng quát, vì rule đầu tiên khớp sẽ thắng.
// File: src/main/java/com/evotek/shop/security/SecurityConfig.java
// imports: org.springframework.context.annotation.Bean, Configuration,
// org.springframework.security.config.Customizer,
// org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity,
// org.springframework.security.config.annotation.web.builders.HttpSecurity,
// org.springframework.security.config.annotation.web.configuration.EnableWebSecurity,
// org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder,
// org.springframework.security.crypto.password.PasswordEncoder,
// org.springframework.security.web.SecurityFilterChain,
// org.springframework.http.HttpMethod
@Configuration
@EnableWebSecurity
@EnableMethodSecurity // bật @PreAuthorize, @PostAuthorize, @PreFilter
public class SecurityConfig {
@Bean
SecurityFilterChain web(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/", "/login", "/css/**").permitAll()
.requestMatchers("/admin/**").hasRole("ADMIN")
.requestMatchers(HttpMethod.DELETE, "/api/orders/**").hasAuthority("orders:write")
.requestMatchers("/api/orders/**").hasAuthority("orders:read")
.requestMatchers("/account/**").authenticated()
.anyRequest().denyAll())
.formLogin(Customizer.withDefaults())
.logout(Customizer.withDefaults());
return http.build();
}
@Bean
PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder();
}
}
anyRequest().denyAll() buộc bạn thêm rule có chủ ý, thay vì quên một endpoint rồi mở toang. Rule theo HTTP method phải đứng trước rule chung của cùng path, nếu không DELETE sẽ rơi vào nhánh orders:read. Vì matcher là PathPattern, pattern có ** ở giữa sẽ ném lỗi lúc khởi động.
Chặn ở cấp method với @EnableMethodSecurity
Method security trả lời câu hỏi URL không trả lời được: người này có được gọi hành động này trên dữ liệu này không. Nó chạy trên proxy AOP, nên chỉ áp dụng cho method public được gọi từ bean khác.
// File: src/main/java/com/evotek/shop/orders/OrderAdminService.java
// imports: org.springframework.security.access.prepost.*,
// org.springframework.stereotype.Service,
// java.util.List
public record OrderView(long id, String ownerUsername, java.math.BigDecimal total) { }
@Service
public class OrderAdminService {
@PreAuthorize("hasRole('ADMIN')")
public void deleteOrder(long orderId) {
// xóa đơn: chỉ ADMIN
}
@PostAuthorize("returnObject.ownerUsername() == authentication.name or hasRole('ADMIN')")
public OrderView find(long orderId) {
// đọc đơn: chủ sở hữu hoặc ADMIN
return null;
}
@PreFilter(value = "filterObject.ownerUsername() == authentication.name",
filterTarget = "views")
public int archiveMine(List<OrderView> views) {
return views.size();
}
}
@PostAuthorize chạy sau khi method đã thực thi, nên chỉ dùng cho đọc; thao tác ghi dùng @PreAuthorize. @PreFilter lọc bớt phần tử thay vì từ chối — người dùng nhận kết quả đã cắt, không nhận 403. Nó không nhận array: truyền array ném IllegalStateException, hãy dùng List hoặc Set.
Role hierarchy: ADMIN ⇒ MANAGER ⇒ USER
Nếu ADMIN phải làm được mọi thứ MANAGER làm, đừng gán ba role cho một người. Khai báo quan hệ kéo theo một lần:
// File: src/main/java/com/evotek/shop/security/SecurityConfig.java (tiếp)
// imports: org.springframework.security.access.hierarchicalroles.*
@Bean
static RoleHierarchy roleHierarchy() {
return RoleHierarchyImpl.fromHierarchy("""
ROLE_ADMIN > ROLE_MANAGER
ROLE_MANAGER > ROLE_USER
""");
}
Dấu > nghĩa là “bao gồm”: người chỉ có ROLE_ADMIN qua được hasRole('MANAGER'), ở cả luật URL lẫn @PreAuthorize, vì bean RoleHierarchy được cả hai tự nhận. Chỉ dùng hierarchy cho quan hệ thật giữa các vị trí; dùng nó để che role explosion sẽ khiến câu “ai được xóa đơn” không còn trả lời được bằng danh sách role.
Vì sao RBAC đơn thuần sụp đổ
RBAC trả lời tốt “người này thuộc nhóm nào”, nhưng kém bốn câu khác:
- Role explosion. “Quản lý xem báo cáo nhưng không xuất file” sinh ra
MANAGER_READONLY. Mỗi tổ hợp quyền thành một role, bảng role thành bản sao của bảng quyền. - Đa tenant.
ROLE_ADMINkhông mang tenant. Admin công ty A không được chạm dữ liệu công ty B, nhưng chuỗi authority giống hệt. - Luật phụ thuộc dữ liệu. “Chỉ sửa đơn của mình”, “chỉ duyệt khoản dưới 50 triệu” không phải câu hỏi về role.
- Least privilege. Khi role phình ra, không ai biết role cho phép gì, và không trả lời được “tháng trước ai có quyền này”.
Triệu chứng rõ nhất: bạn đặt tên role theo hành động thay vì theo vị trí. Lúc đó bạn cần permission, không phải thêm role.
Bước sang permission-based
Permission là authority dạng resource:action: orders:read, orders:write, invoices:export. Role thành một gói permission, không còn được kiểm tra trong code. Rule đọc đúng thứ nó cần:
// File: src/main/java/com/evotek/shop/orders/OrderService.java
// imports: org.springframework.security.access.prepost.PreAuthorize,
// org.springframework.stereotype.Service
@Service
public class OrderService {
@PreAuthorize("hasAuthority('orders:write') and @tenantGuard.sameTenant(#orderId)")
public void cancel(long orderId) {
// hủy đơn trong tenant hiện tại
}
}
@tenantGuard là @Component("tenantGuard") đọc tenant từ Authentication và so với tenant của đơn: quyền đến từ permission, phạm vi đến từ dữ liệu. Spring Security không hỗ trợ wildcard kiểu orders:*; nếu cần, viết bean kiểm tra riêng thay vì nhồi wildcard vào authority.
Bảy lỗi làm hỏng RBAC
1. Tiền tố bị nhân đôi
Đây là lỗi phổ biến nhất vì biểu hiện chỉ là 403. Viết test khẳng định chuỗi authority sau khi nạp user: ROLE_ADMIN phải có, ROLE_ROLE_ADMIN không được có.
2. Tin role trong JWT mà không kiểm chứng
Token là dữ liệu do client giữ. Đọc claim roles mà chưa cấu hình JwtDecoder với JWK set, issuer và thời hạn nghĩa là phân quyền theo nội dung client tự viết. Lỗi thứ hai nằm trong converter: JwtGrantedAuthoritiesConverter mặc định đọc claim scope với tiền tố SCOPE_, nên claim roles không bao giờ khớp hasRole nếu không đổi cấu hình:
// File: src/main/java/com/evotek/shop/security/JwtConfig.java
// gắn vào filter: http.oauth2ResourceServer(o -> o.jwt(j -> j.jwtAuthenticationConverter(converter)))
// imports: org.springframework.security.oauth2.server.resource.authentication.*,
// org.springframework.context.annotation.Bean
@Bean
JwtAuthenticationConverter jwtAuthenticationConverter() {
JwtGrantedAuthoritiesConverter authorities = new JwtGrantedAuthoritiesConverter();
authorities.setAuthoritiesClaimName("roles"); // claim chứa role
authorities.setAuthorityPrefix("ROLE_"); // khớp quy ước hasRole
JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
converter.setJwtGrantedAuthoritiesConverter(authorities);
return converter;
}
3. Authority cũ sau khi đổi role
Authentication là ảnh chụp lúc đăng nhập: với session nó nằm trong HttpSession, với JWT nó nằm trong token. Thu hồi role không làm ảnh chụp đó đổi — người đó giữ quyền cũ đến khi session hoặc token hết hạn. Ba cách xử lý: access token ngắn hạn cộng refresh, xóa session qua SessionRegistry khi role đổi, hoặc thêm cột version vào users và so trong một filter. Chọn cách nào cũng được, miễn bạn biết độ trễ thu hồi quyền.
4. Tự kiểm tra role trong controller
if (authentication.getAuthorities().contains(...)) trong controller là dấu hiệu luật phân quyền đã tản mát: endpoint mới quên kiểm tra, thông điệp lỗi khác nhau, không test tập trung. Đưa kiểm tra về authorizeHttpRequests hoặc @PreAuthorize để từ chối đi qua một AccessDeniedHandler duy nhất.
5. Nhầm @Secured với @PreAuthorize
Ba annotation trông giống nhau nhưng so chuỗi khác nhau, và hai cái sau mặc định không bật trong 7.1.2:
| Annotation | Phải bật | Cách so với authority ROLE_ADMIN |
|---|---|---|
@PreAuthorize("hasRole('ADMIN')") |
Không, bật sẵn | Thêm ROLE_, khớp |
@Secured("ROLE_ADMIN") |
securedEnabled = true |
So nguyên chuỗi, không thêm tiền tố |
@RolesAllowed("ADMIN") |
jsr250Enabled = true |
Tự thêm ROLE_, khớp |
Vì vậy @Secured("ADMIN") và @RolesAllowed("ROLE_ADMIN") đều thất bại — hai annotation ngược nhau về tiền tố. Cả hai không có SpEL, nên code mới chỉ dùng @PreAuthorize.
6. Method security trên private method và self-invocation
Annotation trên method private bị bỏ qua im lặng: proxy không intercept được method private. Lời gọi nội bộ this.method() cũng bỏ qua proxy. Đặt annotation ở method public là điểm vào, hoặc tách sang bean khác. Annotation trên interface có thể không được thấy khi dùng JDK proxy — đặt trên class implementation.
7. Privilege escalation qua mass assignment
Một record UpdateUserRequest(String displayName, String email, Set<String> roles) bind thẳng từ JSON là lỗ hổng tự cấp quyền: client gửi "roles": ["ADMIN"] và thành admin. Tương tự, @PreAuthorize("#req.role == 'ADMIN'") vô nghĩa vì req do client gửi. Chỉ bind field được phép và không cấp quyền dựa trên dữ liệu chưa nạp từ server.
Nhìn về 2027
Spring Security 7.2 mới ở RC, nên 2026 vẫn là năm của 7.1.x. Hai hướng đáng theo dõi: passkey/WebAuthn thành phương thức xác thực mặc định, và phân quyền mịn rời chuỗi authority sang policy engine hoặc kiểm tra theo dữ liệu. @PreAuthorize vẫn là chỗ đặt luật, nhưng biểu thức sẽ gọi bean nghiệp vụ nhiều hơn so role.
Checklist
- Database lưu tên role trần, một mapper duy nhất thêm
ROLE_; test chuỗi authority. anyRequest().denyAll()và rule cụ thể đứng trước rule chung.@EnableMethodSecuritytrên class@Configuration; không dùng@Securedtrong code mới.- Viết
@PreAuthorizetrên method public của service, không trên private method. - Permission dạng
resource:action; tenant và chủ sở hữu kiểm tra bằng dữ liệu, không bằng role. - Biết độ trễ thu hồi quyền: session, token TTL, hay version trong token.
Đọc tiếp Spring Security 101: xác thực vs phân quyền để chắc lại nền tảng, hướng dẫn cấu hình xác thực cho phần đăng nhập, và JWT authentication trong Spring Boot cho phần token. Toàn bộ thứ tự bài nằm ở lộ trình Spring Boot.



