--- title: Keycloak --- # 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**](https://github.com/Captcha-La/captchala-keycloak). Dos opciones: - **Descargar la versión publicada** (recomendado) — descarga `keycloak-captchala-.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 ```bash 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`](https://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`](https://github.com/Captcha-La/captchala-keycloak) - Versiones publicadas (JAR): [`github.com/Captcha-La/captchala-keycloak/releases`](https://github.com/Captcha-La/captchala-keycloak/releases) - Issues / solicitudes de funciones: se abren contra el repositorio anterior - Relacionado: [SDK Web](/es/web-sdk) · [Referencia de la API](/es/api-reference)