Keycloak

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 añades a 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) está en el repositorio: github.com/Caputchin/caputchin-keycloak. Cuenta con unos 15 minutos desde una cuenta nueva hasta la primera sesión verificada en el servidor.

Funciona con Keycloak 26.x (la distribución Quarkus). Necesitas acceso al despliegue de Keycloak para añadir un JAR de proveedor y ejecutar kc.sh build, y una cuenta de administrador del realm que proteges.

1. Crea una clave de sitio

Inicia sesión en caputchin.com/login (tu primer inicio de sesión crea la cuenta), abre tu equipo Personal, haz clic en Crear clave de sitio, ponle el nombre de tu realm de Keycloak y haz clic en Crear. Copia los dos valores:

la Clave pública (cpt_pub_...),
el Secreto (cpt_sec_...). Solo se muestra una vez.

Crea tu cuenta y tu primera clave de sitio recorre las mismas pantallas con más detalle.

2. Instala la extensión

Descarga caputchin-keycloak.jar desde la última versión, cópialo en el directorio providers/ de Keycloak y reconstruye:

cp 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. En una imagen de contenedor, copia el JAR y ejecuta el build dentro de la imagen:

FROM quay.io/keycloak/keycloak:26.4
COPY caputchin-keycloak.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build

Si prefieres compilar el JAR desde el código fuente, mira la guía de instalación del repositorio.

3. Dale el secreto a Keycloak

Deja el secreto fuera de la configuración del realm: defínelo como variable de entorno en el servidor de Keycloak, por ejemplo CAPUTCHIN_SECRET, y reinicia Keycloak. En el paso 5 solo introduces el nombre de la variable. También funcionan un secreto literal o una referencia ${vault.*}; mira la guía de configuración del repositorio.

Hay dos formas, y eliges por realm.

Llave en mano: el theme incluido

El JAR incluye un theme de inicio de sesión caputchin. En la Admin Console, abre tu realm, ve a Realm settings → Themes, pon Login theme en caputchin y haz clic en Save. El widget se renderiza en las páginas de inicio de sesión, restablecimiento y registro sin editar plantillas. Es la vía más rápida si usas un inicio de sesión de Keycloak de serie.

Si entregas un theme de inicio de sesión propio (por ejemplo un theme React de Keycloakify), conserva tu theme y ejecuta 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 <caputchin-widget> (o <caputchin-game>). 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.

5. Enlázala al flujo de inicio de sesión

Keycloak no cambia el autenticador de un paso en su sitio, así que añades el paso de Caputchin a una copia del flujo y quitas el paso original.

Ve a Authentication. En el flujo browser, abre el menú (⋮), haz clic en Duplicate, ponle nombre a la copia (por ejemplo browser caputchin) y haz clic en Duplicate.
En la copia, busca el subflujo forms. Haz clic en su botón + (Add), elige Add execution, selecciona Caputchin Username Password Form y haz clic en Add.
Arrastra el paso nuevo al principio del subflujo forms, por encima del subflujo Conditional 2FA, para que se ejecute donde se ejecutaba el paso antiguo. Su requisito es Required.
Borra el paso original Username Password Form del subflujo forms.
Haz clic en el engranaje (Settings) del paso de Caputchin y rellena:
- Alias: cualquier nombre, como caputchin-login.
- Site key: tu clave pública (cpt_pub_...), el único valor que se envía al navegador.
- Secret key env var: el nombre de la variable del paso 3, como CAPUTCHIN_SECRET.
Luego haz clic en Save. Los demás campos tienen valores por defecto que funcionan: Widget mode checkbox (o invisible, o game), Locale kc (sigue el locale del realm) y Fail closed activado, así que una caída de la verificación bloquea los inicios de sesión en vez de dejarlos pasar.
Abre el menú Action del flujo, haz clic en Bind flow, deja Browser flow y haz clic en Save.

El reto se renderiza en la misma página que las credenciales, no como un paso aparte. Con los ajustes por defecto, la comprobación se ejecuta cuando el usuario hace clic en Sign In.

Restablecimiento de contraseña y registro

El mismo patrón protege los otros dos formularios:

Flujo	Añade este paso	En lugar de
Reset credentials	Caputchin Reset Credential - Choose User	Choose User
Registration	Caputchin, en el subflujo del formulario de registro, con Required	(se añade junto a Registration User Creation)

Cada paso de Caputchin tiene sus propios ajustes (engranaje), así que introduce la clave de sitio y la variable del secreto en cada uno. No añadas un reto al flujo de direct grant: ahí no hay navegador, así que rompería las peticiones de token por API. Binding to flows en el repositorio muestra la misma configuración como JSON de exportación del realm.

El look más rico (qué juego, skins, marca) se ajusta una sola vez en el panel de Caputchin sobre la propia clave de sitio, así que no lo repites en Keycloak.

6. Revisa la Content Security Policy

La Content Security Policy de inicio de sesión por defecto de Keycloak (en Realm settings → Security defenses → Headers) es frame-src 'self'; frame-ancestors 'self'; object-src 'none';. Restringe frames, no scripts ni conexiones, y el juego se ejecuta en un frame srcdoc, así que la checkbox, el widget invisible y el juego funcionan con ella sin cambios.

Si defines una política más estricta propia, parte de la que está en la guía de CSP del repositorio. Una directiva script-src también se aplica a los scripts inline del propio Keycloak, así que prueba la página de inicio de sesión y la Account Console después de cualquier cambio.

La verificación del lado del servidor (de Keycloak al host de verificación) es una llamada de servidor a servidor y la política del navegador no le afecta.

7. Confirma la primera sesión verificada en el servidor

Abre el inicio de sesión de tu aplicación (o la página de inicio de sesión del realm) en una ventana privada.
Inicia sesión con un usuario de prueba. El widget se ejecuta cuando haces clic en Sign In, y Keycloak te deja entrar.
En el panel de Caputchin, abre tu equipo y haz clic en tu clave de sitio. Actualiza las estadísticas.

Verificadas en el servidor marca ahora al menos 1: Keycloak confirmó un token con Caputchin. Esa es tu primera sesión verificada. Si la página de inicio de sesión muestra "Verification failed. Please complete the check and try again." y Verificadas en el servidor sigue en 0, el token nunca llegó a Keycloak: busca un error de Content Security Policy en la consola del navegador (paso 6). Si Completadas en el cliente subió pero el inicio de sesión sigue fallando, comprueba que la variable del secreto del paso 3 está definida en el servidor. Estadística y sesiones explica cada número.

Pruébalo localmente

El repositorio incluye un Keycloak local de un solo comando (e2e/) conectado a un stack de Caputchin local, para que puedas recorrer los tres flujos protegidos antes de desplegar. Mira el README del repositorio.