---
title: Keycloak
---

# 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**](https://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>.jar` từ trang Releases của kho lưu trữ.
- **Biên dịch từ nguồn** — `git clone` kho và chạy `mvn clean package`; file JAR sẽ được tạo trong thư mục `target/`.

Plugin yêu cầu Keycloak ≥ 26 (Quarkus) và Java 17.

### 2. Triển khai

```bash
cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# khởi động lại Keycloak
```

Sau đó đặ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`](https://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`](https://github.com/Captcha-La/captchala-keycloak)
- Bản phát hành (JAR): [`github.com/Captcha-La/captchala-keycloak/releases`](https://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](/vi/web-sdk) · [Tham chiếu API](/vi/api-reference)