Tại sao Keycloak Roles không hoạt động trong Spring Security và cách khắc phục triệt để

Bài viết được dịch và tổng hợp từ tin tức gốc. Bạn có thể đọc bài viết gốc bằng tiếng Anh tại đây.

Điểm tin nhanh:

• Keycloak mặc định không đưa roles vào claim 'authorities' của JWT mà nằm trong cấu trúc lồng nhau.
• Spring Security cần một Custom JwtAuthenticationConverter để trích xuất roles từ realm_access hoặc resource_access.
• Việc cấu hình sai Mapper trong Keycloak là nguyên nhân phổ biến nhất khiến ứng dụng không nhận diện được quyền hạn.

Việc tích hợp Keycloak với Spring Security thường là lựa chọn hàng đầu cho các hệ thống microservices hiện đại nhờ khả năng quản lý định danh tập trung. Tuy nhiên, không ít lập trình viên rơi vào tình trạng dở khóc dở cười khi cấu hình xong xuôi, user đã đăng nhập thành công nhưng các annotation như @PreAuthorize("hasRole('ADMIN')") lại luôn trả về 403 Forbidden. Vấn đề không nằm ở sự phức tạp của framework, mà nằm ở cách Spring Security "đọc" cấu trúc JWT mà Keycloak cung cấp.

Bản chất của vấn đề: Cấu trúc JWT Claim

Khi bạn sử dụng Keycloak làm Identity Provider, các thông tin về role không nằm ở cấp độ root của JWT. Thay vào đó, chúng được đóng gói trong các claim đặc thù như realm_access hoặc resource_access. Mặc định, Spring Security chỉ tìm kiếm quyền hạn trong các claim đơn giản, dẫn đến việc nó "mù" trước cấu trúc JSON phức tạp mà Keycloak gửi tới.

Nếu bạn đang gặp lỗi này, hãy kiểm tra lại cấu trúc token của mình. Thông thường, dữ liệu sẽ trông như sau:

{
  "realm_access": {
    "roles": ["user", "admin"]
  }
}

Spring Security không tự động hiểu rằng mảng roles bên trong realm_access chính là danh sách các quyền hạn của người dùng. Để giải quyết, bạn cần một bộ chuyển đổi (Converter) tùy chỉnh. Nếu bạn đang xây dựng hệ thống với tư duy tối giản, hãy tham khảo thêm về YAGNI: Triết lý tối giản giúp lập trình viên tránh bẫy thiết kế dư thừa để đảm bảo cấu hình bảo mật không bị quá tải.

Giải pháp: Tùy chỉnh JwtAuthenticationConverter

Để Spring Security nhận diện được roles, bạn cần định nghĩa một JwtAuthenticationConverter trong cấu hình SecurityFilterChain. Đây là nơi bạn hướng dẫn framework trích xuất dữ liệu từ JWT.

Bảng so sánh cấu trúc dữ liệu

Mẹo hay: Việc quản lý quyền hạn cần sự đồng bộ. Nếu bạn đang phát triển các ứng dụng AI, hãy đảm bảo rằng các endpoint bảo mật được kiểm soát chặt chẽ như hướng dẫn trong Hướng dẫn toàn diện về API và Tích hợp trong các ứng dụng xây dựng bằng AI năm 2026.

Triển khai mã nguồn

Bạn cần tạo một class thực thi Converter<Jwt, AbstractAuthenticationToken>. Dưới đây là sơ đồ luồng xử lý:

[JWT Token] ---> [JwtAuthenticationConverter] ---> [Extract Realm Access] ---> [Map to GrantedAuthority] ---> [SecurityContext]

Đoạn code gợi ý để cấu hình trong SecurityConfig:

@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {
    JwtGrantedAuthoritiesConverter converter = new JwtGrantedAuthoritiesConverter();
    converter.setAuthoritiesClaimName("realm_access");
    converter.setAuthorityPrefix("ROLE_");
    
    JwtAuthenticationConverter jwtConverter = new JwtAuthenticationConverter();
    jwtConverter.setJwtGrantedAuthoritiesConverter(converter);
    return jwtConverter;
}

Lưu ý: Hãy cẩn thận với tiền tố ROLE_. Spring Security mặc định yêu cầu tiền tố này cho các annotation @PreAuthorize. Nếu bạn không cấu hình đúng, việc so sánh role sẽ thất bại ngay cả khi dữ liệu đã được trích xuất thành công.

Đánh giá & Lời khuyên Thực tiễn

Từ góc nhìn của một Senior Tech Lead, việc cấu hình bảo mật với Keycloak và Spring Security là bài toán về sự hiểu biết sâu sắc về giao thức OAuth2/OIDC.

• Ưu điểm: Giải pháp này giúp tách biệt hoàn toàn logic quản lý user và logic nghiệp vụ, tăng tính bảo mật và khả năng mở rộng.
• Nhược điểm: Cấu hình thủ công JwtAuthenticationConverter có thể trở nên cồng kềnh nếu hệ thống của bạn có nhiều client và nhiều realm khác nhau.
• Phạm vi ứng dụng: Phù hợp cho các hệ thống Microservices quy mô lớn. Đối với các dự án nhỏ, hãy cân nhắc liệu bạn có thực sự cần sự phức tạp này hay không, giống như cách chúng ta cân nhắc trong Tại sao đã đến lúc bạn ngừng copy-paste Repository và tự xây dựng Starter CLI cho riêng mình.

Câu hỏi thường gặp (FAQ)

Tại sao tôi đã thêm role trong Keycloak nhưng Spring vẫn báo 403?

Khả năng cao là do bạn chưa cấu hình JwtAuthenticationConverter để trích xuất đúng đường dẫn (path) của claim chứa roles trong JWT.

Có cách nào không cần viết code Converter không?

Bạn có thể sử dụng tính năng 'Add to access token' trong Keycloak Mapper để đưa roles ra ngoài root của JWT, nhưng cách này không khuyến khích vì làm tăng kích thước token và giảm tính bảo mật.

Làm sao để debug token đang nhận được?

Hãy sử dụng các công cụ như jwt.io để giải mã token và kiểm tra xem claim realm_access hoặc resource_access có tồn tại đúng như mong đợi hay không.

Kết luận

Việc Keycloak roles không hoạt động trong Spring Security thường chỉ là vấn đề về cách ánh xạ dữ liệu. Khi đã hiểu rõ cấu trúc JWT và cách tùy chỉnh JwtAuthenticationConverter, bạn hoàn toàn có thể kiểm soát hệ thống phân quyền của mình một cách chuyên nghiệp. Hãy tiếp tục tối ưu hóa codebase của bạn và đừng quên theo dõi hi_dev để cập nhật những kiến thức kỹ thuật chuyên sâu nhất. Nếu bạn đang gặp vấn đề tương tự trong các dự án thực tế, hãy để lại bình luận phía dưới để chúng ta cùng thảo luận sâu hơn.