Keycloak
CaptchaLa 官方 Keycloak 插件。无需编写任何代码，即可为 Keycloak 内置的登录、注册和重置密码页面添加 CAPTCHA 验证，并在服务端完成校验。以单个 provider JAR 形式发布，直接放入 Keycloak 即可。
覆盖范围
以下每个流程均以独立认证步骤的形式接入 —— 您只需保护想要防护的页面即可。
- 浏览器登录（用户名 / 密码表单）
- 自助注册
- 重置密码（"忘记密码"页面）
验证码默认以浮动控件（float）形式渲染，也可配置为点击弹出的模态框（popup）。
安装
1. 获取 JAR 包
插件已开源，地址： github.com/Captcha-La/captchala-keycloak。两种方式：
- 下载 release 包（推荐）—— 在仓库的 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 设置 → 主题 → 登录主题 → captchala。
3. 获取密钥
在 dash.captcha.la 注册账号，创建一个应用，然后复制：
- App Key —— 公钥，会嵌入到页面中
- App Secret —— 仅在服务端使用，由 Keycloak 用于签发一次性 token 并调用
/v1/validate
4. 接入流程
在管理控制台中，将对应的执行步骤添加到您希望保护的每个流程，然后点击齿轮图标粘贴您的 App Key 和 App Secret：
- 浏览器登录 —— 复制 browser 流程，将 Username Password Form 替换为 Captchala Username Password Form（REQUIRED），并将其绑定为 Realm 的浏览器流程。
- 注册 —— 复制 registration 流程，在注册表单子流程中添加 Captchala Registration（REQUIRED），并将其绑定为 Realm 的注册流程。
- 重置密码 —— 复制 reset credentials 流程，将 Choose User 替换为 Captchala Reset Credential (choose user)（REQUIRED），并将其绑定为 Realm 的重置凭据流程。
在隐私窗口中打开任意一个受保护的页面，确认验证码正常渲染。
配置项
每个执行步骤均通过各自的齿轮图标独立配置。只要密钥已填写，默认值即可开箱即用。
| 配置项 | Key | 默认值 | 说明 |
|---|---|---|---|
| App Key | app.key | — | 来自 CaptchaLa 控制台的公钥。必填。 |
| App Secret | app.secret | — | 服务端密钥。必填。以脱敏形式存储，不会暴露给浏览器。 |
| 渲染模式 | product | float | float（浮动控件）或 popup（模态框）。 |
| Action 标签 | action | 按流程 | 验证时上送的 action 值（login、register、reset）。 |
| 语言 | language | Realm 语言 | 控件语言；留空则跟随 Keycloak 的语言设置。 |
| 失败时拒绝 | fail.closed | true | CaptchaLa API 不可达时，拒绝本次提交。关闭则改为失败放行。 |
| 使用服务端 token | use.server.token | true | 渲染时由服务端签发一次性 token，提供更强的防重放保护。 |
常见问题
插件免费吗？
是的，Keycloak 插件免费且开源。CaptchaLa 免费额度为每月 10,000 次验证 —— 仅在需要更高用量时才会涉及付费计划。
支持哪些 Keycloak 版本？
Keycloak 26+ Quarkus 发行版，基于 26.5.6 与 Java 17 构建。将 JAR 放入 providers/ 目录，运行 kc.sh build 后重启即可。
可以保护哪些页面？
浏览器登录、自助注册和重置密码。每个页面独立接入各自的流程，可根据需要保护其中一个、两个或全部三个。
App Secret 会暴露给浏览器吗？
不会。密钥以脱敏形式存储，仅在 Keycloak 向 CaptchaLa API 发起请求时通过 X-App-Secret 请求头传输，不会出现在任何页面、模板或日志中。每次挑战均使用一次性 token 完成验证，因此已解过的 token 无法被重放。
CaptchaLa API 不可达时会怎样？
默认情况下插件会失败关闭（拒绝本次提交）。可在任意执行步骤上将 fail.closed 关闭，改为失败放行 —— 适合灰度上线，不建议在生产环境中使用。
源码
- 插件仓库：
github.com/Captcha-La/captchala-keycloak - Release 下载（JAR）：
github.com/Captcha-La/captchala-keycloak/releases - 问题反馈 / 需求建议：在上述仓库提 issue
- 相关文档：Web SDK · API 参考