Keycloak

Keycloak 是一个服务器，而不是一个你嵌入脚本的页面，所以 Caputchin 以一个 Keycloak extension 的形式交付：一个你丢进 Keycloak 的 provider JAR。它在登录、密码重置和注册页面上渲染 Caputchin 组件，并在流程继续之前从 Keycloak 内部核验令牌。复选框组件和游戏都能用。

这个 extension 是开源的。完整参考（每一项配置属性、realm 导出的 JSON、theme 契约，以及一份兼容性矩阵）都住在仓库里：github.com/Caputchin/caputchin-keycloak。

1. 安装这个 extension

构建 provider JAR 并把它放进 Keycloak，然后重新构建：

# build (no JDK on the host? run it in Docker)
docker run --rm -v "$PWD":/work -w /work maven:3.9-eclipse-temurin-21 mvn -DskipTests package

cp target/caputchin-keycloak.jar "$KEYCLOAK_HOME/providers/"
"$KEYCLOAK_HOME/bin/kc.sh" build
"$KEYCLOAK_HOME/bin/kc.sh" start --optimized

要让 Keycloak 发现这些 provider，kc.sh build 是必需的。

2. 挑选组件如何渲染

有两种方式，而且你按 realm 来选。

开箱即用：自带的 theme（无需自定义 theme）

JAR 自带一个 caputchin 登录 theme。在 Realm Settings → Themes → Login theme: caputchin 下设好它，组件就会在登录、重置和注册页面上渲染，无需编辑模板。如果你用的是原装的 Keycloak 登录，这是最快的路子。

如果你出一个自定义登录 theme（例如一个 Keycloakify 的 React theme），那就保留你的 theme，让这个 extension 以无头方式运行。它把组件配置暴露进页面上下文并校验令牌；你的 theme 渲染 <caputchin-widget>（或 <caputchin-game>）元素，并用你的设计令牌为它设样式。令牌字段是 caputchin-token。完整的属性契约和一个 Keycloakify 示例在仓库的 theme 指南里。

3. 把它绑定到你的流程

在 Authentication → Flows 里，复制你想保护的那个流程，并替换 execution：

流程	把 execution 设为
Browser (login)	Caputchin Username Password Form
Reset Credentials	Caputchin Reset Credential - Choose User
Registration	把 Caputchin 添加到注册表单

登录和重置的挑战渲染在与凭据相同的页面上，而不是作为一个单独的步骤。打开每个 execution 的配置（齿轮）来设你的密钥。不要给 direct grant 流程添加挑战：那里没有浏览器，所以那会弄坏经 API 的令牌请求。

4. 配置密钥

在 execution 配置里，设：

站点密钥：你的公钥（cpt_pub_...）。送往浏览器的唯一值。
密钥：你的密钥（cpt_sec_...）。你可以把它存为字面值，指向一个环境变量（这样它绝不会落进你的 realm 导出里），或者用一个 ${vault.*} 引用。
组件模式：checkbox、invisible 或 game。再加上尺寸、locale（默认跟随 realm 的 locale）和皮肤。
故障即关：默认开启，这样一次核验中断会拦截，而不是放机器人通过。

更丰富的外观（哪个游戏、皮肤、品牌）只在 Caputchin 仪表盘里就站点密钥本身设一次，所以你不必在这里重复。

5. 在你的 Content Security Policy 里放行组件

Keycloak 默认的登录 CSP 比组件所需的更严。在 Realm Settings → Security Defenses → Content Security Policy 下，放行加载器脚本、验证主机和 WebAssembly。确切的值在仓库的 CSP 指南里。

在本地试一试

仓库包含一个一条命令的本地 Keycloak（e2e/），它接到一个本地 Caputchin 栈上，让你在部署前把三个设了关的流程都点一遍。见仓库 README。