Keycloak

Официальный плагин CaptchaLa для Keycloak. Добавляет проверку CAPTCHA к встроенным экранам входа, регистрации и сброса пароля Keycloak, с проверкой на стороне сервера, без написания кода. Поставляется в виде единого JAR с провайдером, который вы помещаете в Keycloak.

Что охватывает

Каждый из приведённых ниже потоков подключается как отдельный шаг аутентификации — вы защищаете только те экраны, которые хотите.

• Вход в браузере (форма имени пользователя / пароля)
• Самостоятельная регистрация
• Сброс пароля (экран «забыл пароль»)

По умолчанию проверка отображается как плавающий виджет (float) или как модальное окно по клику (popup).

Установка

1. Получите JAR

Плагин с открытым исходным кодом доступен по адресу github.com/Captcha-La/captchala-keycloak. Два варианта:

• Скачать релиз (рекомендуется) — возьмите keycloak-captchala-<version>.jar со страницы Releases в репозитории.
• Собрать из исходников — 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

Затем установите тему входа: Realm settings → Themes → Login theme → captchala.

3. Получите ключи

Зарегистрируйтесь на dash.captcha.la, создайте приложение и скопируйте:

• App Key — публичный, встраивается в страницу
• App Secret — только для сервера, используется Keycloak для выпуска одноразового токена и вызова /v1/validate

4. Подключите потоки

В консоли администратора добавьте соответствующий исполнитель в каждый поток, который хотите защитить, затем нажмите на значок шестерёнки, чтобы вставить App Key и App Secret:

• Вход в браузере — продублируйте поток browser, замените Username Password Form на Captchala Username Password Form (REQUIRED), привяжите его как поток browser для области.
• Регистрация — продублируйте поток registration, добавьте Captchala Registration (REQUIRED) в подпоток registration-form, привяжите его как поток регистрации для области.
• Сброс пароля — продублируйте поток reset credentials, замените Choose User на Captchala Reset Credential (choose user) (REQUIRED), привяжите его как поток reset-credentials для области.

Откройте один из защищённых экранов в приватном окне, чтобы убедиться, что проверка отображается.

Конфигурация

Каждый исполнитель настраивается независимо через значок шестерёнки. Настройки по умолчанию работают сразу после установки ключей.

Настройка	Ключ	По умолчанию	Описание
App Key	app.key	—	Публичный ключ из панели управления CaptchaLa. Обязательно.
App Secret	app.secret	—	Серверный секрет. Обязательно. Хранится в маскированном виде, никогда не передаётся в браузер.
Базовый URL API	api.base	https://apiv1.captcha.la	Базовый URL API CaptchaLa.
URL скрипта виджета	script.url	https://api.captcha.la/sdk/jslib/captchala.js	Адрес загрузки JavaScript виджета.
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	Если API CaptchaLa недоступен, отправка блокируется. Отключите, чтобы разрешать отправку при сбое.
Использовать серверный токен	use.server.token	true	Выпускать одноразовый серверный токен при рендеринге для усиленной защиты от повторного использования.

FAQ

Плагин бесплатный?

Да. Плагин для Keycloak бесплатный и с открытым исходным кодом. Бесплатный план CaptchaLa покрывает 10 000 проверок в месяц — платные планы нужны, только если требуется больший объём.

Какие версии Keycloak поддерживаются?

Keycloak 26+ на дистрибутиве Quarkus, собранный против версии 26.5.6 с Java 17. Поместите JAR в providers/, выполните kc.sh build и перезапустите.

Какие экраны можно защитить?

Вход в браузере, самостоятельная регистрация и сброс пароля. Каждый добавляется в свой поток независимо, поэтому можно защитить один, два или все три.

App Secret когда-либо передаётся в браузер?

Нет. Секрет хранится в маскированном виде и передаётся только в заголовке X-App-Secret от Keycloak к API CaptchaLa. Он никогда не появляется ни на одной странице, в шаблоне или логе. Каждая проверка верифицируется с помощью одноразового токена, поэтому решённый токен нельзя использовать повторно.

Что происходит, если API CaptchaLa недоступен?

По умолчанию плагин блокирует отправку (fail closed). Установите fail.closed в off на любом исполнителе, чтобы разрешать отправку при сбое — полезно для поэтапного выкатывания, но не рекомендуется для продакшена.

Исходный код

• Репозиторий плагина: github.com/Captcha-La/captchala-keycloak
• Релизы (JAR): github.com/Captcha-La/captchala-keycloak/releases
• Issues / feature-запросы: в репозитории выше
• Связанное: Web SDK · Справочник API