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	—	伺服端密鑰。必填。以遮罩方式儲存，永不暴露給瀏覽器。
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
• 發行版（JAR）：github.com/Captcha-La/captchala-keycloak/releases
• 問題回報 / 功能建議：請在上述儲存庫開 issue
• 相關文件：Web SDK · API 參考