---
type: how-to
title: Keycloak
summary: "Protege con Caputchin el inicio de sesión, el restablecimiento de contraseña y el registro de Keycloak: instala la extensión, elige un modo de render y verifica el token del lado del servidor."
---
Keycloak es un servidor, no una página en la que incrustas un script, así que Caputchin se entrega como una **extensión** de Keycloak: un JAR de proveedor que sueltas dentro de Keycloak. Renderiza el widget de Caputchin en las páginas de inicio de sesión, restablecimiento de contraseña y registro, y verifica el token desde dentro de Keycloak antes de que el flujo continúe. Funcionan tanto el widget de checkbox como el juego.
La extensión es de código abierto. La referencia completa (cada propiedad de configuración, el JSON de exportación del realm, el contrato del theme y una matriz de compatibilidad) vive en el repositorio: [github.com/Caputchin/caputchin-keycloak](https://github.com/Caputchin/caputchin-keycloak).
Funciona con Keycloak 26.x (la distribución Quarkus). Necesitas acceso al despliegue de Keycloak para añadir un JAR de proveedor y correr `kc.sh build`; esto no es una app de marketplace alojada.
## 1. Instala la extensión
Construye el JAR de proveedor y colócalo en Keycloak, luego reconstruye:
```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` es necesario para que Keycloak descubra los proveedores.
## 2. Elige cómo se renderiza el widget
Hay dos formas, y eliges por realm.
### Llave en mano: el theme incluido (sin theme propio)
El JAR incluye un theme de inicio de sesión `caputchin`. Ponlo en **Realm Settings → Themes → Login theme: `caputchin`**, y el widget se renderiza en las páginas de inicio de sesión, restablecimiento y registro sin editar plantillas. Esta es la vía más rápida si usas un inicio de sesión de Keycloak de serie.
### Headless: tu propio theme renderiza el widget
Si entregas un theme de inicio de sesión propio (por ejemplo un theme React de Keycloakify), conserva tu theme y corre la extensión en modo headless. Expone la configuración del widget al contexto de la página y valida el token; tu theme renderiza el elemento `` (o ``) y lo estiliza con tus design tokens. El campo del token es `caputchin-token`. El contrato completo de atributos y un ejemplo de Keycloakify están en la [guía del theme del repositorio](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/theme-contract.md).
## 3. Enlázala a tus flujos
En **Authentication → Flows**, duplica el flujo que quieres proteger e intercambia la ejecución:
| Flujo | Pon la ejecución en |
| --- | --- |
| Browser (login) | Caputchin Username Password Form |
| Reset Credentials | Caputchin Reset Credential - Choose User |
| Registration | añade Caputchin al formulario de registro |
Los retos de inicio de sesión y restablecimiento se renderizan en la misma página que las credenciales, no como un paso aparte. Abre la configuración de cada ejecución (el engranaje) para poner tus claves. No añadas un reto al flujo de direct grant: ahí no hay navegador, así que rompería las peticiones de token por API.
## 4. Configura las claves
En la configuración de la ejecución, pon:
- **Clave de sitio**: tu clave pública (`cpt_pub_...`). El único valor que se envía al navegador.
- **Clave secreta**: tu secreto (`cpt_sec_...`). Puedes guardarla como literal, apuntar a una variable de entorno (para que nunca caiga en tu exportación del realm), o usar una referencia `${vault.*}`.
- **Modo del widget**: `checkbox`, `invisible` o `game`. Más el tamaño, el locale (por defecto sigue el locale del realm) y el skin.
- **Fallo cerrado**: activado por defecto, así que una caída de la verificación bloquea en vez de dejar pasar a los bots.
El look más rico (qué juego, skins, marca) se ajusta una sola vez en el [panel de Caputchin](https://caputchin.com) sobre la propia clave de sitio, así que no lo repites aquí.
## 5. Permite el widget en tu Content Security Policy
La CSP de inicio de sesión por defecto de Keycloak es más estricta de lo que el widget necesita. En **Realm Settings → Security Defenses → Content Security Policy**, permite el script del cargador, el host de verificación y WebAssembly. El valor exacto está en la [guía de CSP del repositorio](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/csp.md).
La verificación del lado del servidor (de Keycloak al host de verificación) es una llamada de servidor a servidor y no le afecta la CSP del navegador. Solo le afecta al tráfico del widget del lado del navegador.
## Pruébalo localmente
El repositorio incluye un Keycloak local de un solo comando (`e2e/`) cableado a un stack de Caputchin local, para que puedas clicar por los tres flujos protegidos antes de desplegar. Mira el [README del repositorio](https://github.com/Caputchin/caputchin-keycloak).