Keycloak
Plugin Keycloak chính thức của CaptchaLa. Thêm thử thách CAPTCHA vào các màn hình đăng nhập, đăng ký và đặt lại mật khẩu tích hợp sẵn của Keycloak, được xác minh phía máy chủ, mà không cần viết bất kỳ dòng mã nào. Được đóng gói dưới dạng một file JAR provider duy nhất để thả vào Keycloak.
Phạm vi bảo vệ
Mỗi luồng dưới đây được gắn vào như một bước xác thực riêng biệt — bạn chỉ bảo vệ các màn hình bạn muốn.
- Đăng nhập trình duyệt (biểu mẫu tên người dùng / mật khẩu)
- Tự đăng ký
- Đặt lại mật khẩu (màn hình "quên mật khẩu")
Thử thách hiển thị mặc định là widget nổi (float), hoặc dạng modal mở khi nhấp (popup).
Cài đặt
1. Lấy file JAR
Plugin là mã nguồn mở tại github.com/Captcha-La/captchala-keycloak. Hai cách:
- Tải bản phát hành (khuyến nghị) — lấy
keycloak-captchala-<version>.jartừ trang Releases của kho lưu trữ. - Biên dịch từ nguồn —
git clonekho và chạymvn clean package; file JAR sẽ được tạo trong thư mụctarget/.
Plugin yêu cầu Keycloak ≥ 26 (Quarkus) và Java 17.
2. Triển khai
cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# khởi động lại KeycloakSau đó đặt theme đăng nhập: Realm settings → Themes → Login theme → captchala.
3. Lấy khóa của bạn
Đăng ký tại dash.captcha.la, tạo một ứng dụng, sau đó sao chép:
- App Key — khóa công khai, được nhúng vào trang
- App Secret — chỉ dùng phía máy chủ, được Keycloak sử dụng để tạo token một lần và gọi
/v1/validate
4. Kết nối các luồng
Trong bảng quản trị, thêm execution phù hợp vào từng luồng bạn muốn bảo vệ, sau đó nhấp biểu tượng bánh răng để dán App Key và App Secret:
- Đăng nhập trình duyệt — nhân bản luồng browser, thay Username Password Form bằng Captchala Username Password Form (REQUIRED), gán làm luồng browser của realm.
- Đăng ký — nhân bản luồng registration, thêm Captchala Registration (REQUIRED) vào sub-flow registration-form, gán làm luồng đăng ký của realm.
- Đặt lại mật khẩu — nhân bản luồng reset credentials, thay Choose User bằng Captchala Reset Credential (choose user) (REQUIRED), gán làm luồng reset-credentials của realm.
Mở một trong các màn hình được bảo vệ trong cửa sổ riêng tư để xác nhận thử thách hiển thị đúng.
Cấu hình
Mỗi execution được cấu hình độc lập từ biểu tượng bánh răng của nó. Các giá trị mặc định hoạt động ngay khi đã thiết lập khóa.
| Cài đặt | Key | Mặc định | Mô tả |
|---|---|---|---|
| App Key | app.key | — | Khóa công khai từ bảng điều khiển CaptchaLa. Bắt buộc. |
| App Secret | app.secret | — | Bí mật máy chủ. Bắt buộc. Được lưu có che, không bao giờ lộ ra trình duyệt. |
| URL API gốc | api.base | https://apiv1.captcha.la | API gốc của CaptchaLa. |
| URL script widget | script.url | https://api.captcha.la/sdk/jslib/captchala.js | Nguồn tải JS widget. |
| URL CSS widget | css.url | https://api.captcha.la/sdk/jslib/captchala.css | Nguồn tải CSS widget. |
| Chế độ hiển thị | product | float | float (widget nổi) hoặc popup (modal). |
| Nhãn action | action | theo luồng | Giá trị action gửi khi xác minh (login, register, reset). |
| Ngôn ngữ | language | locale của realm | Ngôn ngữ widget; để trống sẽ theo locale của Keycloak. |
| Chặn khi thất bại | fail.closed | true | Khi API CaptchaLa không truy cập được, từ chối lượt gửi. Tắt để cho qua khi thất bại. |
| Dùng token máy chủ | use.server.token | true | Tạo token một lần phía máy chủ khi render để chống phát lại mạnh hơn. |
Câu hỏi thường gặp
Plugin có miễn phí không?
Có. Plugin Keycloak miễn phí và là mã nguồn mở. Gói miễn phí của CaptchaLa bao gồm 10.000 lượt xác minh mỗi tháng — gói trả phí chỉ áp dụng khi bạn cần lưu lượng cao hơn.
Những phiên bản Keycloak nào được hỗ trợ?
Keycloak 26+ trên bản phân phối Quarkus, biên dịch với 26.5.6 và Java 17. Thả file JAR vào providers/, chạy kc.sh build và khởi động lại.
Có thể bảo vệ những màn hình nào?
Đăng nhập trình duyệt, tự đăng ký và đặt lại mật khẩu. Mỗi luồng được thêm độc lập, vì vậy bạn có thể bảo vệ một, hai hoặc cả ba.
App Secret có bao giờ lộ ra trình duyệt không?
Không. Secret được lưu có che và chỉ được gửi trong header X-App-Secret từ Keycloak đến API CaptchaLa. Nó không bao giờ xuất hiện trong bất kỳ trang, template hay log nào. Mỗi thử thách được xác minh bằng token dùng một lần, nên token đã giải không thể phát lại.
Điều gì xảy ra nếu API CaptchaLa không truy cập được?
Theo mặc định plugin sẽ chặn khi thất bại (lượt gửi bị từ chối). Tắt fail.closed trên bất kỳ execution nào để cho qua khi thất bại — hữu ích cho rollout từng giai đoạn, không khuyến nghị cho production.
Mã nguồn
- Kho plugin:
github.com/Captcha-La/captchala-keycloak - Bản phát hành (JAR):
github.com/Captcha-La/captchala-keycloak/releases - Lỗi / yêu cầu tính năng: gửi vào kho lưu trữ ở trên
- Liên quan: Web SDK · Tham chiếu API