---
type: how-to
title: Keycloak
summary: "用 Caputchin 为 Keycloak 的登录、密码重置和注册设关：安装这个 extension，挑一个渲染模式，并在服务端核验令牌。"
---

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

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

<Callout type="info">
适用于 Keycloak 26.x（Quarkus 发行版）。要添加一个 provider JAR 并运行 `kc.sh build`，你需要对 Keycloak 部署的访问权限；这不是一个托管的应用市场应用。
</Callout>

## 1. 安装这个 extension

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

```bash
# 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 来渲染组件

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

## 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 仪表盘](https://caputchin.com)里就站点密钥本身设一次，所以你不必在这里重复。

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

Keycloak 默认的登录 CSP 比组件所需的更严。在 **Realm Settings → Security Defenses → Content Security Policy** 下，放行加载器脚本、验证主机和 WebAssembly。确切的值在[仓库的 CSP 指南](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/csp.md)里。

<Callout type="info">
服务端核验（Keycloak 到验证主机）是一次服务器到服务器的调用，不受浏览器 CSP 影响。受影响的只有浏览器一侧的组件流量。
</Callout>

## 在本地试一试

仓库包含一个一条命令的本地 Keycloak（`e2e/`），它接到一个本地 Caputchin 栈上，让你在部署前把三个设了关的流程都点一遍。见[仓库 README](https://github.com/Caputchin/caputchin-keycloak)。