Keycloak

Keycloak はサーバーであって、スクリプトを埋め込むページではありません。そのため Caputchin は Keycloak の extension として提供されます。Keycloak に追加する provider JAR です。これがログイン、パスワードリセット、登録のページに Caputchin ウィジェットをレンダリングし、フローが進む前に Keycloak の内側でトークンを検証します。チェックボックスのウィジェットもゲームも、どちらも動きます。

この extension はオープンソースです。完全なリファレンス（すべての設定プロパティ、realm エクスポートの JSON、theme の契約、互換性マトリクス）はリポジトリにあります: github.com/Caputchin/caputchin-keycloak。新しいアカウントから最初のサーバー側で検証されたセッションまで、約 15 分を見込んでください。

1. サイトキーを作成する

caputchin.com/login でサインインし（最初のサインインでアカウントが作成されます）、個人 チームを開いて サイトキーを作成 をクリックし、Keycloak の realm にちなんだ名前を付けて 作成 をクリックします。次の 2 つの値をコピーします:

• 公開鍵（cpt_pub_...）
• シークレット（cpt_sec_...）。一度しか表示されません。

アカウントと最初のサイトキーを作成する では、同じ画面をより詳しく説明しています。

2. extension をインストールする

最新のリリース から caputchin-keycloak.jar をダウンロードし、Keycloak の providers/ ディレクトリにコピーして、再ビルドします:

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

Keycloak が provider を発見するには kc.sh build が必要です。コンテナイメージでは、イメージの中で JAR をコピーしてビルドを実行します:

FROM quay.io/keycloak/keycloak:26.4
COPY caputchin-keycloak.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build

代わりにソースから JAR をビルドするには、リポジトリのインストールガイド を参照してください。

3. Keycloak にシークレットを渡す

シークレットは realm の設定に入れないでください。Keycloak サーバーの環境変数（たとえば CAPUTCHIN_SECRET）として設定し、Keycloak を再起動します。手順 5 では変数名だけを入力します。シークレットをそのまま入れる方法や ${vault.*} 参照も使えます。リポジトリの設定ガイド を参照してください。

4. ウィジェットのレンダリング方法を選ぶ

方法は 2 つあり、realm ごとに選びます。

ターンキー: 同梱の theme

JAR には caputchin ログイン theme が同梱されています。Admin Console で realm を開き、Realm settings → Themes に進んで Login theme を caputchin に設定し、Save をクリックします。テンプレートを編集せずに、ログイン、リセット、登録のページにウィジェットがレンダリングされます。素の Keycloak ログインを使うなら、これが最速の道です。

ヘッドレス: 独自の theme がウィジェットをレンダリングする

独自のログイン theme（たとえば Keycloakify の React theme）を使っているなら、theme はそのままにして extension をヘッドレスで動かします。extension はウィジェットの設定をページのコンテキストに公開してトークンを検証し、theme が <caputchin-widget>（または <caputchin-game>）要素をレンダリングします。トークンのフィールドは caputchin-token です。属性の完全な契約と Keycloakify の例は リポジトリの theme ガイド にあります。

5. ログインフローにバインドする

Keycloak ではステップの authenticator をその場で変更できないので、フローのコピーに Caputchin のステップを追加し、元のステップを削除します。

1. Authentication に進みます。browser フローでメニュー（⋮）を開き、Duplicate をクリックし、コピーに名前を付けて（たとえば browser caputchin）、Duplicate をクリックします。

2. コピーの中で forms サブフローを見つけます。その +（Add）ボタンをクリックし、Add execution を選んで Caputchin Username Password Form を選択し、Add をクリックします。

3. 新しいステップを forms サブフローの先頭、Conditional 2FA サブフローの上までドラッグし、元のステップがあった位置で実行されるようにします。要件は Required です。

4. forms サブフローから元の Username Password Form ステップを削除します。

5. Caputchin ステップの歯車（Settings）をクリックし、次を入力します:

   • Alias: 任意の名前。たとえば caputchin-login。
   • Site key: 公開鍵（cpt_pub_...）。ブラウザに送られる唯一の値です。
   • Secret key env var: 手順 3 の変数名。たとえば CAPUTCHIN_SECRET。

   続けて Save をクリックします。ほかの欄には動作する既定値があります。Widget mode は checkbox（または invisible、game）、Locale は kc（realm の locale に従います）、Fail closed はオンで、検証の障害時にはサインインを通すのではなくブロックします。

6. フローの Action メニューを開き、Bind flow をクリックし、Browser flow のまま Save をクリックします。

チャレンジは別のステップとしてではなく、資格情報と同じページにレンダリングされます。既定の設定では、ユーザーが Sign In をクリックしたときにチェックが実行されます。

パスワードリセットと登録

同じやり方で、残りの 2 つのフォームも保護できます:

Caputchin のステップはそれぞれ独自の設定（歯車）を持つので、それぞれにサイトキーとシークレットの変数を入力してください。direct grant のフローにはチャレンジを追加しないでください。そこにはブラウザがないので、API のトークンリクエストを壊してしまいます。リポジトリの フローへのバインド では、同じ設定を realm エクスポートの JSON で示しています。

より豊かな見た目（どのゲーム、スキン、ブランド）は Caputchin ダッシュボード でサイトキー自体に一度だけ設定するので、Keycloak で繰り返す必要はありません。

6. Content Security Policy を確認する

Keycloak の既定のログイン Content Security Policy（Realm settings → Security defenses → Headers）は frame-src 'self'; frame-ancestors 'self'; object-src 'none'; です。これはフレームを制限するもので、スクリプトや通信は制限しません。またゲームは srcdoc フレームで動くので、チェックボックス、invisible ウィジェット、ゲームのいずれも、このポリシーのままで動きます。

独自にもっと厳しいポリシーを設定する場合は、リポジトリの CSP ガイド にあるものから始めてください。script-src ディレクティブは Keycloak 自身のインラインスクリプトにも適用されるので、変更したらログインページと Account Console をテストしてください。

サーバー側の検証（Keycloak から検証ホストへ）はサーバー間の呼び出しで、ブラウザのポリシーの影響を受けません。

7. 最初のサーバー側で検証されたセッションを確認する

1. プライベートウィンドウで、アプリケーションのログイン（または realm のログインページ）を開きます。
2. テストユーザーでサインインします。Sign In をクリックするとウィジェットが実行され、Keycloak がサインインさせます。
3. Caputchin ダッシュボード でチームを開き、サイトキーをクリックします。統計を更新します。

サーバー側で検証済み が 1 以上になっていれば、Keycloak が Caputchin でトークンを確認したということです。これが最初の検証済みセッションです。ログインページに "Verification failed. Please complete the check and try again." と表示され、サーバー側で検証済み が 0 のままなら、トークンは Keycloak に届いていません。ブラウザのコンソールで Content Security Policy のエラーを確認してください（手順 6）。クライアント側で完了 が増えたのにサインインが失敗し続ける場合は、手順 3 のシークレットの変数がサーバーに設定されているか確認してください。各数値の意味は 統計とセッション で説明しています。

ローカルで試す

リポジトリには、ローカルの Caputchin スタックに配線された 1 コマンドのローカル Keycloak（e2e/）が含まれており、デプロイ前にゲートされた 3 つのフローすべてをクリックして試せます。リポジトリの README を参照してください。

あわせて読む

• サイトキーの概要
• WordPress