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 --optimizedKeycloak が 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 ガイド にあります。
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 ダッシュボード でサイトキー自体に一度だけ設定するので、ここでは繰り返しません。
5. Content Security Policy でウィジェットを許可する
Keycloak の既定のログイン CSP は、ウィジェットに必要なものより厳しめです。Realm Settings → Security Defenses → Content Security Policy で、ローダースクリプト、検証ホスト、WebAssembly を許可してください。正確な値は リポジトリの CSP ガイド にあります。
ローカルで試す
リポジトリには、ローカルの Caputchin スタックに配線された 1 コマンドのローカル Keycloak（e2e/）が含まれており、デプロイ前にゲートされた 3 つのフローすべてをクリックして通せます。リポジトリの README を参照してください。