---
title: Keycloak
---

# Keycloak

CaptchaLa 官方 Keycloak 外掛。無需撰寫任何程式碼，即可在 Keycloak 內建的登入、註冊與重設密碼頁面加上 CAPTCHA 驗證，並由伺服端驗證。以單一 provider JAR 部署，放入 Keycloak 即可使用。

## 涵蓋範圍

下列每一條流程皆以獨立的驗證步驟接入 —— 只保護您實際需要的頁面即可。

- 瀏覽器登入（帳號密碼表單）
- 自助式註冊
- 重設密碼（「忘記密碼」頁面）

驗證挑戰預設以浮動小工具呈現（`float`），亦可切換為點擊後展開的彈出視窗（`popup`）。

## 安裝

### 1. 取得 JAR

外掛以開源形式發布：
[**github.com/Captcha-La/captchala-keycloak**](https://github.com/Captcha-La/captchala-keycloak)。兩種方式：

- **下載發行版**（推薦）—— 從儲存庫的 Releases 頁面下載 `keycloak-captchala-<version>.jar`。
- **從原始碼建置** —— `git clone` 儲存庫後執行 `mvn clean package`；JAR 輸出至 `target/`。

外掛需要 Keycloak ≥ 26（Quarkus）與 Java 17。

### 2. 部署外掛

```bash
cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# 重新啟動 Keycloak
```

接著設定登入主題：**Realm settings → Themes → Login theme → `captchala`**。

### 3. 取得金鑰

於 [`dash.captcha.la`](https://dash.captcha.la) 註冊帳號、建立一個應用，然後複製：

- **App Key** —— 公開金鑰，會嵌入頁面中
- **App Secret** —— 僅伺服端使用，由 Keycloak 簽發一次性 token 並呼叫 `/v1/validate` 時使用

### 4. 串接流程

在管理控制台中，將對應的 execution 加入您要保護的流程，再點擊齒輪圖示貼上 **App Key** 與 **App Secret**：

- **瀏覽器登入** —— 複製 *browser* 流程，以 **Captchala Username Password Form**（REQUIRED）取代 **Username Password Form**，並綁定為 realm 的瀏覽器流程。
- **註冊** —— 複製 *registration* 流程，在 registration-form 子流程中加入 **Captchala Registration**（REQUIRED），並綁定為 realm 的註冊流程。
- **重設密碼** —— 複製 *reset credentials* 流程，以 **Captchala Reset Credential (choose user)**（REQUIRED）取代 **Choose User**，並綁定為 realm 的重設憑證流程。

在無痕視窗中開啟其中一個受保護的頁面，確認驗證挑戰能正常呈現。

## 設定項目

每個 execution 皆透過其齒輪圖示獨立設定。金鑰設定完畢後，預設值即可開箱即用。

| 設定項目 | Key | 預設值 | 說明 |
| --- | --- | --- | --- |
| App Key | `app.key` | — | 來自 CaptchaLa 控制台的公開金鑰。必填。 |
| App Secret | `app.secret` | — | 伺服端密鑰。必填。以遮罩方式儲存，永不暴露給瀏覽器。 |
| API base URL | `api.base` | `https://apiv1.captcha.la` | CaptchaLa API 基礎位址。 |
| Widget script URL | `script.url` | `https://api.captcha.la/sdk/jslib/captchala.js` | 小工具 JS 的載入位址。 |
| Widget CSS URL | `css.url` | `https://api.captcha.la/sdk/jslib/captchala.css` | 小工具 CSS 的載入位址。 |
| 顯示模式 | `product` | `float` | `float`（浮動小工具）或 `popup`（彈出視窗）。 |
| Action 標籤 | `action` | 依流程而定 | 驗證時送出的 `action` 值（`login`、`register`、`reset`）。 |
| 語言 | `language` | realm 語系 | 小工具語言；留空則跟隨 Keycloak 的 locale 設定。 |
| 失敗關閉 | `fail.closed` | `true` | CaptchaLa API 無法連線時拒絕提交。設為 off 可改為失敗放行。 |
| 使用伺服器 token | `use.server.token` | `true` | 在渲染時簽發一次性伺服器 token，強化防重放能力。 |

## 常見問題

**外掛是免費的嗎？**

是的。Keycloak 外掛免費且開源。CaptchaLa 免費方案包含每月 10,000 次驗證 —— 僅在需要更高用量時才會涉及付費方案。

**支援哪些 Keycloak 版本？**

Keycloak 26+ 的 Quarkus 發行版，以 Java 17 針對 26.5.6 版本建置。將 JAR 放入 `providers/`，執行 `kc.sh build`，然後重新啟動。

**可以保護哪些頁面？**

瀏覽器登入、自助式註冊以及重設密碼。每條流程皆獨立加入，可以只保護其中一條、兩條或全部三條。

**App Secret 會暴露給瀏覽器嗎？**

不會。密鑰以遮罩方式儲存，僅在 Keycloak 向 CaptchaLa API 發送請求時，透過 `X-App-Secret` 標頭傳遞，不會出現在任何頁面、範本或日誌中。每次挑戰皆使用一次性 token 驗證，因此已解的 token 無法被重放。

**如果 CaptchaLa API 無法連線怎麼辦？**

外掛預設為失敗關閉（提交被拒絕）。在任一 execution 上將 `fail.closed` 設為 off 可改為失敗放行 —— 適合灰度上線，不建議用於正式環境。

## 原始碼

- 外掛儲存庫：[`github.com/Captcha-La/captchala-keycloak`](https://github.com/Captcha-La/captchala-keycloak)
- 發行版（JAR）：[`github.com/Captcha-La/captchala-keycloak/releases`](https://github.com/Captcha-La/captchala-keycloak/releases)
- 問題回報 / 功能建議：請在上述儲存庫開 issue
- 相關文件：[Web SDK](/zh-TW/web-sdk) · [API 參考](/zh-TW/api-reference)