Triển Khai Role-Based Access Control trong Spring Security | Java Spring Roadmap

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.

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ùng jakarta.annotation.security.RolesAllowed, không còn javax.
  • requestMatchers("/admin/**") so khớp bằng PathPatternRequestMatcher theo PathPattern của Spring MVC, không phải Ant matcher: ** chỉ hợp lệ ở cuối pattern, nên /admin/**/edit không parse được.
  • @EnableMethodSecurity là công tắc duy nhất: prePostEnabled=true mặc định, còn securedEnabled=false và jsr250Enabled=false. @Secured và @RolesAllowed không tự hoạt động.
  • WebSecurityConfigurerAdapter đã bị xóa từ Security 6. Luật URL chạy qua AuthorizationManager, không còn AccessDecisionManager và 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_ADMIN khô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.
  • @EnableMethodSecurity trên class @Configuration; không dùng @Secured trong code mới.
  • Viết @PreAuthorize trê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.