---
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)。两种方式：

- **下载 release 包**（推荐）—— 在仓库的 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 设置 → 主题 → 登录主题 → `captchala`**。

### 3. 获取密钥

在 [`dash.captcha.la`](https://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` | — | 服务端密钥。必填。以脱敏形式存储，不会暴露给浏览器。 |
| API 基础 URL | `api.base` | `https://apiv1.captcha.la` | CaptchaLa API 基础地址。 |
| 控件脚本 URL | `script.url` | `https://api.captcha.la/sdk/jslib/captchala.js` | 控件 JS 的加载地址。 |
| 控件样式 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 的语言设置。 |
| 失败时拒绝 | `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`](https://github.com/Captcha-La/captchala-keycloak)
- Release 下载（JAR）：[`github.com/Captcha-La/captchala-keycloak/releases`](https://github.com/Captcha-La/captchala-keycloak/releases)
- 问题反馈 / 需求建议：在上述仓库提 issue
- 相关文档：[Web SDK](/zh-CN/web-sdk) · [API 参考](/zh-CN/api-reference)