Keycloak
CaptchaLa 官方 Keycloak 外掛。無需撰寫任何程式碼，即可在 Keycloak 內建的登入、註冊與重設密碼頁面加上 CAPTCHA 驗證，並由伺服端驗證。以單一 provider JAR 部署，放入 Keycloak 即可使用。
涵蓋範圍
下列每一條流程皆以獨立的驗證步驟接入 —— 只保護您實際需要的頁面即可。
- 瀏覽器登入（帳號密碼表單）
- 自助式註冊
- 重設密碼（「忘記密碼」頁面）
驗證挑戰預設以浮動小工具呈現（float），亦可切換為點擊後展開的彈出視窗（popup）。
安裝
1. 取得 JAR
外掛以開源形式發布： github.com/Captcha-La/captchala-keycloak。兩種方式：
- 下載發行版（推薦）—— 從儲存庫的 Releases 頁面下載
keycloak-captchala-<version>.jar。 - 從原始碼建置 ——
git clone儲存庫後執行mvn clean package；JAR 輸出至target/。
外掛需要 Keycloak ≥ 26（Quarkus）與 Java 17。
2. 部署外掛
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 註冊帳號、建立一個應用，然後複製：
- 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 | — | 伺服端密鑰。必填。以遮罩方式儲存，永不暴露給瀏覽器。 |
| 顯示模式 | 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 - 發行版（JAR）：
github.com/Captcha-La/captchala-keycloak/releases - 問題回報 / 功能建議：請在上述儲存庫開 issue
- 相關文件：Web SDK · API 參考