Keycloak là gì? Hướng dẫn tích hợp Keycloak với Spring Boot

Bảo mật là một trong những yếu tố quan trọng nhất khi phát triển ứng dụng, đặc biệt là khi bạn phải quản lý danh tính và quyền truy cập của nhiều người dùng.

Mặc dù việc tự xây dựng hệ thống xác thực và phân quyền từ đầu hoàn toàn nằm trong khả năng của các developer, nhưng nó thường tốn nhiều thời gian và công sức, nhất là khi bạn cần tích hợp các giao thức tiêu chuẩn như OAuth2 hoặc OpenID Connect.

Keycloak không chỉ giúp bạn giảm bớt gánh nặng khi triển khai các tính năng xác thực mà còn mang lại sự tiện lợi, tính nhất quán và khả năng tùy chỉnh cao. Bạn có thể dễ dàng tích hợp đăng nhập từ Google, Facebook hay thiết lập hệ thống đăng nhập một lần (SSO) chỉ trong vài bước.

Trong bài viết này, chúng ta sẽ cùng tìm hiểu:

1. Keycloak là gì và tại sao nó lại được nhiều developer yêu thích đến vậy.
2. Làm thế nào để tích hợp Keycloak vào một ứng dụng Spring Boot chỉ trong vài bước đơn giản.

1. Keycloak là gì?

Keycloak là một nền tảng mã nguồn mở phổ biến, cung cấp giải pháp đăng nhập một lần (SSO) và quản lý danh tính, quyền truy cập cho các ứng dụng và dịch vụ.

Mục tiêu của Keycloak là đơn giản hóa bảo mật, giúp các nhà phát triển dễ dàng tích hợp các tính năng bảo mật vào ứng dụng mà không cần phải tự xây dựng từ đầu. Những tính năng này đã được cung cấp sẵn, có thể tùy chỉnh linh hoạt để phù hợp với từng tổ chức.

Keycloak hỗ trợ các giao diện người dùng tùy chỉnh cho đăng nhập, đăng ký tài khoản, quản lý người dùng, và quản trị hệ thống. Ngoài ra, nó còn có khả năng tích hợp với các hệ thống quản lý danh tính hiện có như LDAP (Lightweight Directory Access Protocol) hoặc Active Directory, đồng thời hỗ trợ xác thực thông qua các nhà cung cấp bên thứ ba như Facebook và Google.

Hiểu đơn giản: Nếu bạn là một developer, Keycloak giống như một công cụ all-in-one để xử lý các vấn đề liên quan đến xác thực và quản lý quyền truy cập. Thay vì phải tự code các tính năng như đăng nhập, phân quyền, hay tích hợp với bên thứ ba, bạn chỉ cần sử dụng Keycloak.

2. Các thành phần chính của Keycloak

Để hiểu cách Keycloak hoạt động, chúng ta sẽ đi sâu vào các thành phần chính trong hệ thống và cách chúng tương tác với nhau. 

2.1. Realm (Không gian quản lý)

Realm là một không gian làm việc độc lập trong Keycloak, mỗi realm quản lý các người dùng (user), vai trò (role), nhóm (group), và ứng dụng riêng biệt.

Bạn có thể có nhiều realm, ví dụ:

• Internal: Quản lý nhân viên trong nội bộ công ty.
• External: Quản lý khách hàng hoặc đối tác bên ngoài.

2.2 User (Người dùng)

User đại diện cho cá nhân hoặc hệ thống truy cập vào ứng dụng. Người dùng có thể được gán vai trò (roles) để xác định quyền truy cập.

Keycloak hỗ trợ các phương thức xác thực đa dạng:

• Đăng nhập bằng email/mật khẩu.
• Đăng nhập qua các nhà cung cấp bên thứ ba (Google, Facebook).
• Xác thực hai yếu tố (2FA).

2.3 Role (Vai trò)

Vai trò được sử dụng để quản lý quyền truy cập, có thể định nghĩa vai trò ở cấp độ ứng dụng (client role) hoặc ở cấp độ realm (realm role).

2.4 Client (Ứng dụng)

Client đại diện cho các ứng dụng hoặc dịch vụ được bảo mật bởi Keycloak. Mỗi client có cấu hình riêng, bao gồm giao thức (OAuth2, OpenID Connect), URL callback, và thông tin bảo mật như client secret.

2.5 Token (Mã xác thực)

Keycloak sử dụng token để xác thực và ủy quyền, bao gồm:

• Access Token: Được gửi cùng với các yêu cầu đến ứng dụng để xác minh người dùng.
• ID Token: Chứa thông tin về danh tính của người dùng.
• Refresh Token: Dùng để lấy access token mới khi token cũ hết hạn.

Khi một người dùng đăng nhập vào ứng dụng, Keycloak trả về:

• Access Token: Hợp lệ trong 10 phút.
• Refresh Token: Hợp lệ trong 30 phút, k hi access token hết hạn, ứng dụng sẽ sử dụng refresh token để yêu cầu token mới mà không cần yêu cầu người dùng đăng nhập lại.

3. Keycloak hoạt động như thế nào?

1. Người dùng truy cập ứng dụng: Người dùng mở ứng dụng (ví dụ: http://myapp.com) và yêu cầu truy cập tài nguyên.
2. Ứng dụng chuyển hướng đến Keycloak: Nếu người dùng chưa đăng nhập, ứng dụng sẽ chuyển hướng đến Keycloak để thực hiện xác thực.
3. Keycloak xác thực người dùng: Người dùng nhập thông tin đăng nhập (hoặc sử dụng Google, Facebook). Nếu xác thực thành công, Keycloak tạo các token (Access Token, ID Token, Refresh Token).
4. Keycloak trả token về ứng dụng: Ứng dụng nhận token từ Keycloak và lưu lại (thường trong cookie hoặc local storage).
5. Ứng dụng sử dụng token để truy cập tài nguyên: Khi người dùng yêu cầu tài nguyên (API, dữ liệu), ứng dụng gửi Access Token kèm theo yêu cầu để chứng minh danh tính.
6. Keycloak kiểm tra quyền truy cập: Keycloak xác minh token, kiểm tra vai trò và trả về dữ liệu nếu người dùng có quyền.

4. Hướng dẫn Tích hợp Keycloak vào Ứng dụng (sử dụng Docker)

4.1 Cài đặt và Chạy Keycloak với Docker

Sử dụng lệnh sau để khởi chạy Keycloak trên môi trường Docker:

docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

• KEYCLOAK_ADMIN và KEYCLOAK_ADMIN_PASSWORD là thông tin đăng nhập mặc định, bạn có thể thay đổi nếu cần.
• Keycloak sẽ chạy tại http://localhost:8080.

Truy cập giao diện quản trị:

• Mở trình duyệt và truy cập http://localhost:8080/admin.
• Đăng nhập với thông tin admin (admin/admin).

4.2 Cấu hình Realm và Client

Đăng nhập vào giao diện quản trị với tài khoản admin, chọnCreate Realm, đặt tên realm (ví dụ: myrealm), và nhấp Create.

Trong realm vừa tạo, chuyển đến tab Clients, nhấp Create và nhập thông tin:

• Client ID: my-app.
• Client Protocol: openid-connect.
• Root URL: URL ứng dụng của bạn (ví dụ: http://localhost:3000).

Chọn client vừa tạo và cập nhật các thông số:

• Access Type: confidential (bảo mật cao) hoặc public (dành cho frontend).
• Redirect URI: Thêm URL callback của ứng dụng (ví dụ: http://localhost:3000/*).
• Nếu Access Type là confidential, vào tab Credentials và lưu lại Client Secret.

4.3 Thêm người dùng

Chuyển đến tab Users trong realm, nhấp Add User, nhập các thông tin cơ bản (username, email), và nhấp Save.

Chuyển đến tab Credentials của người dùng, đặt mật khẩu, và tắt tùy chọn Temporary nếu bạn không muốn yêu cầu người dùng đổi mật khẩu sau lần đầu đăng nhập.

4.4 Tích hợp Keycloak vào Ứng dụng (Spring Boot)

Thêm thư viện Keycloak vào filepom.xml.

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-spring-boot-starter</artifactId>
    <version>{phiên bản mới nhất}</version>
</dependency>

Cấu hình file application.properties.

keycloak.auth-server-url=http://localhost:8080
keycloak.realm=myrealm
keycloak.resource=my-app
keycloak.credentials.secret={Client Secret}
keycloak.bearer-only=true
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8080/realms/myrealm

Cấu hình Spring Security, tạo lớp bảo mật.

@Configuration
@EnableWebSecurity
public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        http.authorizeRequests()
            .antMatchers("/public/**").permitAll()
            .anyRequest().authenticated();
    }
}

Khởi động ứng dụng và kiểm tra tính năng đăng nhập thông qua Keycloak.

Các bài viết liên quan:

• Idempotent Consumer: Xử lý thông điệp trùng lặp trong Microservices
• Hướng dẫn tích hợp Redux và React Query trong dự án React Vite
• Giới thiệu Kiến trúc Backend for Frontend (BFF)
• Spring Boot là gì? Hướng dẫn Khởi tạo Project Spring Boot với Docker