Keycloak

Plugin oficial de CaptchaLa para Keycloak. Añade un reto CAPTCHA a las pantallas integradas de inicio de sesión, registro y restablecimiento de contraseña de Keycloak, verificado en el servidor, sin escribir ningún código. Se distribuye como un único JAR de proveedor que colocas en Keycloak.

Qué cubre

Cada flujo de abajo se conecta como un paso de autenticación independiente — solo proteges las pantallas que quieres.

• Inicio de sesión en el navegador (el formulario de nombre de usuario / contraseña)
• Autorregistro
• Restablecimiento de contraseña (la pantalla de «contraseña olvidada»)

El reto se renderiza como un widget flotante por defecto (float), o como un modal con clic para abrir (popup).

Instalación

1. Obtener el JAR

El plugin es de código abierto en github.com/Captcha-La/captchala-keycloak. Dos opciones:

• Descargar la versión publicada (recomendado) — descarga keycloak-captchala-<version>.jar desde la página de Releases del repositorio.
• Compilar desde el código fuente — git clone el repositorio y ejecuta mvn clean package; el JAR se genera en target/.

El plugin es compatible con Keycloak ≥ 26 (Quarkus) y Java 17.

2. Desplegarlo

cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# reinicia Keycloak

Luego establece el tema de inicio de sesión: Configuración del realm → Temas → Tema de inicio de sesión → captchala.

3. Obtener tus claves

Regístrate en dash.captcha.la, crea una aplicación y copia:

• App Key — pública, incrustada en la página
• App Secret — solo en el servidor, usada por Keycloak para generar un token de un solo uso y llamar a /v1/validate

4. Conectar los flujos

En la consola de administración, añade la ejecución correspondiente a cada flujo que quieras proteger y haz clic en el icono de engranaje para pegar tu App Key y App Secret:

• Inicio de sesión en el navegador — duplica el flujo browser, sustituye Username Password Form por Captchala Username Password Form (REQUIRED) y asígnalo como flujo de inicio de sesión del realm.
• Registro — duplica el flujo registration, añade Captchala Registration (REQUIRED) al subflujo del formulario de registro y asígnalo como flujo de registro del realm.
• Restablecimiento de contraseña — duplica el flujo reset credentials, sustituye Choose User por Captchala Reset Credential (choose user) (REQUIRED) y asígnalo como flujo de restablecimiento de credenciales del realm.

Abre una de las pantallas protegidas en una ventana privada para confirmar que el reto se renderiza.

Configuración

Cada ejecución se configura de forma independiente desde su icono de engranaje. Los valores predeterminados funcionan desde el primer momento una vez que se establecen las claves.

Ajuste	Clave	Por defecto	Descripción
App Key	app.key	—	Clave pública del panel de CaptchaLa. Obligatoria.
App Secret	app.secret	—	Secreto del servidor. Obligatorio. Almacenado de forma enmascarada, nunca expuesto al navegador.
URL base de la API	api.base	https://apiv1.captcha.la	Base de la API de CaptchaLa.
URL del script del widget	script.url	https://api.captcha.la/sdk/jslib/captchala.js	Desde dónde se carga el JS del widget.
URL del CSS del widget	css.url	https://api.captcha.la/sdk/jslib/captchala.css	Desde dónde se carga el CSS del widget.
Modo de renderizado	product	float	float (widget flotante) o popup (modal).
Etiqueta de acción	action	por flujo	La action enviada en la validación (login, register, reset).
Idioma	language	configuración regional del realm	Idioma del widget; vacío sigue la configuración regional de Keycloak.
Fallo cerrado	fail.closed	true	Cuando la API de CaptchaLa no está disponible, deniega el envío. Desactívalo para fallar abierto.
Usar token de servidor	use.server.token	true	Genera un token de servidor de un solo uso en el renderizado para mayor protección anti-repetición.

Preguntas frecuentes

¿Es gratuito el plugin?

Sí. El plugin de Keycloak es gratuito y de código abierto. El plan gratuito de CaptchaLa cubre 10.000 verificaciones al mes — los planes de pago solo aplican si necesitas más volumen.

¿Qué versiones de Keycloak son compatibles?

Keycloak 26+ en la distribución Quarkus, compilado contra 26.5.6 con Java 17. Coloca el JAR en providers/, ejecuta kc.sh build y reinicia.

¿Qué pantallas puede proteger?

Inicio de sesión en el navegador, autorregistro y restablecimiento de contraseña. Cada uno se añade a su flujo de forma independiente, por lo que puedes proteger uno, dos o los tres.

¿Se expone alguna vez el App Secret al navegador?

No. El secreto se almacena de forma enmascarada y solo se envía en la cabecera X-App-Secret de Keycloak a la API de CaptchaLa. Nunca aparece en ninguna página, plantilla ni registro. Cada reto se verifica con un token de un solo uso, por lo que un token resuelto no puede reutilizarse.

¿Qué ocurre si la API de CaptchaLa no está disponible?

Por defecto el plugin falla cerrado (el envío se deniega). Desactiva fail.closed en cualquier ejecución para fallar abierto — útil para un despliegue gradual, no recomendado en producción.

Fuente

• Repositorio del plugin: github.com/Captcha-La/captchala-keycloak
• Versiones publicadas (JAR): github.com/Captcha-La/captchala-keycloak/releases
• Issues / solicitudes de funciones: se abren contra el repositorio anterior
• Relacionado: SDK Web · Referencia de la API