Keycloak
CaptchaLa 公式 Keycloak プラグイン。コードを書かずに、Keycloak 標準のログイン・登録・パスワードリセット画面に CAPTCHA チャレンジを追加し、サーバーサイドで検証します。プロバイダー JAR を 1 つ配置するだけで動作します。
保護対象
以下のフローはそれぞれ独立した認証ステップとして組み込まれます — 保護したい画面だけを選んで有効化できます。
- ブラウザログイン（ユーザー名 / パスワードフォーム）
- セルフ登録
- パスワードリセット（「パスワードをお忘れですか」画面）
チャレンジはデフォルトでフローティングウィジェット（float）として、またはクリックで開くモーダル（popup）として表示されます。
インストール
1. JAR を入手
プラグインは以下でオープンソース公開されています: github.com/Captcha-La/captchala-keycloak。2 つの方法があります。
- リリース版をダウンロード（推奨）— リポジトリの Releases ページから
keycloak-captchala-<version>.jarを取得します。 - ソースからビルド —
git cloneしてリポジトリを取得し、mvn clean packageを実行します。JAR はtarget/以下に生成されます。
本プラグインは Keycloak ≥ 26（Quarkus）および Java 17 を対象としています。
2. デプロイ
cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# Keycloak を再起動次に、ログインテーマを設定します: レルム設定 → テーマ → ログインテーマ → captchala。
3. キーを取得
dash.captcha.la でアカウントを作成してアプリケーションを作り、以下をコピーします。
- App Key — 公開キー、ページに埋め込まれます
- App Secret — サーバー専用、Keycloak がワンタイムトークンを発行して
/v1/validateを呼び出す際に使用します
4. フローを設定
管理コンソールで、保護したいフローに対応する実行（Execution）を追加し、歯車アイコンをクリックして App Key と App Secret を貼り付けます。
- ブラウザログイン — browser フローを複製し、Username Password Form を Captchala Username Password Form（REQUIRED）に置き換えて、レルムのブラウザフローとしてバインドします。
- 登録 — registration フローを複製し、registration-form サブフローに Captchala Registration（REQUIRED）を追加して、レルムの登録フローとしてバインドします。
- パスワードリセット — reset credentials フローを複製し、Choose User を Captchala Reset Credential (choose user)（REQUIRED）に置き換えて、レルムのリセットフローとしてバインドします。
シークレットウィンドウで保護対象の画面を開き、チャレンジが表示されることを確認します。
設定項目
各実行は歯車アイコンから個別に設定できます。キーを設定すれば、デフォルト値のままで動作します。
| 設定項目 | キー | 既定値 | 説明 |
|---|---|---|---|
| App Key | app.key | — | CaptchaLa ダッシュボードの公開キー。必須。 |
| App Secret | app.secret | — | サーバーシークレット。必須。マスクされて保存され、ブラウザに送出されることはありません。 |
| API ベース URL | api.base | https://apiv1.captcha.la | CaptchaLa API ベース URL。 |
| ウィジェットスクリプト URL | script.url | https://api.captcha.la/sdk/jslib/captchala.js | ウィジェット JS の読み込み元。 |
| ウィジェット CSS URL | css.url | https://api.captcha.la/sdk/jslib/captchala.css | ウィジェット CSS の読み込み元。 |
| 表示モード | product | float | float（フローティングウィジェット）または popup（モーダル）。 |
| アクションラベル | action | フローごと | 検証時に送信する action（login、register、reset）。 |
| 言語 | language | レルムのロケール | ウィジェットの言語。空白の場合は Keycloak のロケールに追従します。 |
| フェイルクローズ | fail.closed | true | CaptchaLa API に到達できない場合、送信を拒否します。フェイルオープンにするには OFF にしてください。 |
| サーバートークン使用 | use.server.token | true | レンダリング時にサーバーでワンタイムトークンを発行し、リプレイ攻撃への耐性を高めます。 |
FAQ
プラグインは無料ですか？
無料です。Keycloak プラグインは無料でオープンソースです。CaptchaLa 無料プランでは月 10,000 回の検証が含まれ、それ以上の量が必要な場合のみ有料プランが必要になります。
対応している Keycloak のバージョンは？
Quarkus ディストリビューションの Keycloak 26 以上、Java 17 で 26.5.6 に対してビルドされています。providers/ に JAR を配置し、kc.sh build を実行して再起動してください。
保護できる画面は？
ブラウザログイン、セルフ登録、パスワードリセットです。それぞれのフローに独立して追加できるため、1 つ、2 つ、またはすべての 3 つを保護できます。
App Secret がブラウザに漏れることはありますか？
ありません。シークレットはマスクされて保存され、Keycloak から CaptchaLa API への X-App-Secret ヘッダーとしてのみ送信されます。ページ、テンプレート、ログのいずれにも表示されません。各チャレンジはワンタイムトークンで検証されるため、解決済みトークンは再利用できません。
CaptchaLa API に到達できない場合はどうなりますか？
デフォルトではプラグインはフェイルクローズ（送信を拒否）します。フェイルオープンにするには、任意の実行の fail.closed を OFF に設定してください — 段階的なロールアウトには有効ですが、本番環境では非推奨です。
ソース
- プラグインリポジトリ:
github.com/Captcha-La/captchala-keycloak - リリース（JAR）:
github.com/Captcha-La/captchala-keycloak/releases - 問題報告 / 機能要望: 上記リポジトリの issue へ
- 関連: Web SDK · API リファレンス