---
title: Keycloak
---

# Keycloak

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

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

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

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

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

## Установка

### 1. Получите JAR

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

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

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

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

Зарегистрируйтесь на [`dash.captcha.la`](https://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`](https://github.com/Captcha-La/captchala-keycloak)
- Релизы (JAR): [`github.com/Captcha-La/captchala-keycloak/releases`](https://github.com/Captcha-La/captchala-keycloak/releases)
- Issues / feature-запросы: в репозитории выше
- Связанное: [Web SDK](/ru/web-sdk) · [Справочник API](/ru/api-reference)