---
type: how-to
title: Keycloak
summary: "Закрой воротами вход, сброс пароля и регистрацию Keycloak с Caputchin: установи расширение, выбери режим рендера и проверь токен на стороне сервера."
---

Keycloak это сервер, а не страница, в которую ты встраиваешь скрипт, поэтому Caputchin поставляется как **расширение** Keycloak: provider-JAR, который ты кладёшь в Keycloak. Оно рендерит виджет Caputchin на страницах входа, сброса пароля и регистрации и проверяет токен изнутри Keycloak, прежде чем поток продолжится. Работают и виджет-галочка, и игра.

Расширение с открытым исходным кодом. Полная справка (каждое свойство конфигурации, JSON экспорта realm, контракт темы и матрица совместимости) живёт в репозитории: [github.com/Caputchin/caputchin-keycloak](https://github.com/Caputchin/caputchin-keycloak).

<Callout type="info">
Работает с Keycloak 26.x (дистрибутив Quarkus). Тебе нужен доступ к развёртыванию Keycloak, чтобы добавить provider-JAR и выполнить `kc.sh build`; это не размещённое marketplace-приложение.
</Callout>

## 1. Установи расширение

Собери provider-JAR и помести его в Keycloak, затем пересобери:

```bash
# 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 --optimized
```

`kc.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 есть в [руководстве по теме в репозитории](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/theme-contract.md).

## 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](https://caputchin.com) на самом ключе сайта, так что здесь ты его не повторяешь.

## 5. Разреши виджет в своей Content Security Policy

Стандартная CSP входа Keycloak строже, чем нужно виджету. В **Realm Settings → Security Defenses → Content Security Policy** разреши скрипт загрузчика, хост проверки и WebAssembly. Точное значение есть в [руководстве по CSP в репозитории](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/csp.md).

<Callout type="info">
Проверка на стороне сервера (Keycloak к хосту проверки) это вызов сервер-к-серверу, и браузерная CSP на неё не влияет. Влияет только на браузерный трафик виджета.
</Callout>

## Попробуй локально

Репозиторий включает локальный Keycloak в одну команду (`e2e/`), связанный с локальным стеком Caputchin, чтобы ты мог прокликать все три защищённых потока перед развёртыванием. Смотри [README репозитория](https://github.com/Caputchin/caputchin-keycloak).