---
type: how-to
title: Keycloak
summary: "Keycloak のログイン、パスワードリセット、登録を Caputchin でゲートします。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. ウィジェットのレンダリング方法を選ぶ

方法は 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 に従います）、スキン。
- **Fail closed**：既定でオン。検証の障害時にはボットを通すのではなくブロックします。

より豊かな見た目（どのゲーム、スキン、ブランド）は [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>

## ローカルで試す

リポジトリには、ローカルの Caputchin スタックに配線された 1 コマンドのローカル Keycloak（`e2e/`）が含まれており、デプロイ前にゲートされた 3 つのフローすべてをクリックして通せます。[リポジトリの README](https://github.com/Caputchin/caputchin-keycloak) を参照してください。