Keycloak
Keycloak это сервер, а не страница, в которую ты встраиваешь скрипт, поэтому Caputchin поставляется как расширение Keycloak: provider-JAR, который ты кладёшь в Keycloak. Оно рендерит виджет Caputchin на страницах входа, сброса пароля и регистрации и проверяет токен изнутри Keycloak, прежде чем поток продолжится. Работают и виджет-галочка, и игра.
Расширение с открытым исходным кодом. Полная справка (каждое свойство конфигурации, JSON экспорта realm, контракт темы и матрица совместимости) живёт в репозитории: github.com/Caputchin/caputchin-keycloak.
1. Установи расширение
Собери provider-JAR и помести его в Keycloak, затем пересобери:
# build (no JDK on the host? run it in Docker)
docker run --rm -v "$PWD":/work -w /work maven:3.9-eclipse-temurin-21 mvn -DskipTests package
cp target/caputchin-keycloak.jar "$KEYCLOAK_HOME/providers/"
"$KEYCLOAK_HOME/bin/kc.sh" build
"$KEYCLOAK_HOME/bin/kc.sh" start --optimizedkc.sh build нужен, чтобы Keycloak обнаружил провайдеры.
2. Выбери, как рендерится виджет
Есть два способа, и ты выбираешь для каждого realm.
Под ключ: встроенная тема (своя тема не нужна)
JAR несёт тему входа caputchin. Поставь её в Realm Settings → Themes → Login theme: caputchin, и виджет рендерится на страницах входа, сброса и регистрации без правки шаблонов. Это самый быстрый путь, если ты используешь стандартный вход Keycloak.
Headless: твоя собственная тема рендерит виджет
Если ты поставляешь собственную тему входа (например, React-тему Keycloakify), сохрани свою тему и запусти расширение в headless-режиме. Оно открывает конфигурацию виджета в контекст страницы и валидирует токен; твоя тема рендерит элемент <caputchin-widget> (или <caputchin-game>) и стилизует его твоими design-токенами. Поле токена это caputchin-token. Полный контракт атрибутов и пример Keycloakify есть в руководстве по теме в репозитории.
3. Привяжи его к своим потокам
В Authentication → Flows продублируй поток, который хочешь защитить, и поменяй execution:
| Поток | Поставь execution на |
|---|---|
| Browser (login) | Caputchin Username Password Form |
| Reset Credentials | Caputchin Reset Credential - Choose User |
| Registration | добавь Caputchin в форму регистрации |
Испытания входа и сброса рендерятся на той же странице, что и учётные данные, а не как отдельный шаг. Открой конфигурацию каждого execution (шестерёнку), чтобы задать свои ключи. Не добавляй испытание в поток direct grant: там нет браузера, так что это сломало бы запросы токенов по API.
4. Настрой ключи
В конфигурации execution задай:
- Ключ сайта: твой публичный ключ (
cpt_pub_...). Единственное значение, отправляемое в браузер. - Секретный ключ: твой секрет (
cpt_sec_...). Можешь хранить его как литерал, указать на переменную окружения (чтобы он никогда не попал в твой экспорт realm) или использовать ссылку${vault.*}. - Режим виджета:
checkbox,invisibleилиgame. Плюс размер, locale (по умолчанию следует locale realm) и скин. - Fail closed: включён по умолчанию, так что сбой проверки блокирует, а не пропускает ботов.
Более богатый вид (какая игра, скины, бренд) задаётся один раз в панели Caputchin на самом ключе сайта, так что здесь ты его не повторяешь.
5. Разреши виджет в своей Content Security Policy
Стандартная CSP входа Keycloak строже, чем нужно виджету. В Realm Settings → Security Defenses → Content Security Policy разреши скрипт загрузчика, хост проверки и WebAssembly. Точное значение есть в руководстве по CSP в репозитории.
Попробуй локально
Репозиторий включает локальный Keycloak в одну команду (e2e/), связанный с локальным стеком Caputchin, чтобы ты мог прокликать все три защищённых потока перед развёртыванием. Смотри README репозитория.