---
title: Keycloak
---

# Keycloak

CaptchaLa 公式 Keycloak プラグイン。コードを書かずに、Keycloak 標準のログイン・登録・パスワードリセット画面に CAPTCHA チャレンジを追加し、サーバーサイドで検証します。プロバイダー JAR を 1 つ配置するだけで動作します。

## 保護対象

以下のフローはそれぞれ独立した認証ステップとして組み込まれます — 保護したい画面だけを選んで有効化できます。

- ブラウザログイン（ユーザー名 / パスワードフォーム）
- セルフ登録
- パスワードリセット（「パスワードをお忘れですか」画面）

チャレンジはデフォルトでフローティングウィジェット（`float`）として、またはクリックで開くモーダル（`popup`）として表示されます。

## インストール

### 1. JAR を入手

プラグインは以下でオープンソース公開されています:
[**github.com/Captcha-La/captchala-keycloak**](https://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. デプロイ

```bash
cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# Keycloak を再起動
```

次に、ログインテーマを設定します: **レルム設定 → テーマ → ログインテーマ → `captchala`**。

### 3. キーを取得

[`dash.captcha.la`](https://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`](https://github.com/Captcha-La/captchala-keycloak)
- リリース（JAR）: [`github.com/Captcha-La/captchala-keycloak/releases`](https://github.com/Captcha-La/captchala-keycloak/releases)
- 問題報告 / 機能要望: 上記リポジトリの issue へ
- 関連: [Web SDK](/ja/web-sdk) · [API リファレンス](/ja/api-reference)