Keycloak

Plugin officiel CaptchaLa pour Keycloak. Ajoute un défi CAPTCHA aux écrans de connexion, d'inscription et de réinitialisation de mot de passe intégrés à Keycloak, avec vérification côté serveur, sans écrire la moindre ligne de code. Livré sous la forme d'un unique JAR de fournisseur à déposer dans Keycloak.

Ce qui est couvert

Chaque flux ci-dessous est branché en tant qu'étape d'authentification distincte — vous ne protégez que les écrans que vous souhaitez.

• Connexion navigateur (le formulaire identifiant / mot de passe)
• Auto-inscription
• Réinitialisation de mot de passe (l'écran « mot de passe oublié »)

Le défi s'affiche par défaut sous forme de widget flottant (float), ou comme une modale à l'ouverture au clic (popup).

Installation

1. Obtenir le JAR

Le plugin est open source sur github.com/Captcha-La/captchala-keycloak. Deux options :

• Télécharger la release (recommandé) — récupérez keycloak-captchala-<version>.jar depuis la page Releases du dépôt.
• Compiler depuis les sources — git clone le dépôt et lancez mvn clean package ; le JAR est produit dans target/.

Le plugin cible Keycloak ≥ 26 (Quarkus) et Java 17.

2. Le déployer

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

Définissez ensuite le thème de connexion : Paramètres du realm → Thèmes → Thème de connexion → captchala.

3. Récupérer vos clés

Inscrivez-vous sur dash.captcha.la, créez une application, puis copiez :

• App Key — publique, intégrée dans la page
• App Secret — réservée au côté serveur, utilisée par Keycloak pour émettre un jeton à usage unique et appeler /v1/validate

4. Brancher les flux

Dans la console d'administration, ajoutez l'exécution correspondante à chaque flux à protéger, puis cliquez sur l'icône d'engrenage pour coller votre App Key et votre App Secret :

• Connexion navigateur — dupliquez le flux browser, remplacez Username Password Form par Captchala Username Password Form (REQUIRED), liez-le comme flux browser du realm.
• Inscription — dupliquez le flux registration, ajoutez Captchala Registration (REQUIRED) au sous-flux registration-form, liez-le comme flux d'inscription du realm.
• Réinitialisation de mot de passe — dupliquez le flux reset credentials, remplacez Choose User par Captchala Reset Credential (choose user) (REQUIRED), liez-le comme flux reset-credentials du realm.

Ouvrez l'un des écrans protégés dans une fenêtre privée pour vérifier que le défi s'affiche.

Configuration

Chaque exécution se configure indépendamment depuis son icône d'engrenage. Les valeurs par défaut fonctionnent immédiatement une fois les clés renseignées.

Réglage	Clé	Valeur par défaut	Description
App Key	app.key	—	Clé publique issue du tableau de bord CaptchaLa. Obligatoire.
App Secret	app.secret	—	Secret serveur. Obligatoire. Stocké masqué, jamais exposé au navigateur.
URL de base de l'API	api.base	https://apiv1.captcha.la	Base de l'API CaptchaLa.
URL du script du widget	script.url	https://api.captcha.la/sdk/jslib/captchala.js	Source depuis laquelle le JS du widget est chargé.
URL CSS du widget	css.url	https://api.captcha.la/sdk/jslib/captchala.css	Source depuis laquelle le CSS du widget est chargé.
Mode de rendu	product	float	float (widget flottant) ou popup (modale).
Libellé d'action	action	selon le flux	L'action envoyée lors de la validation (login, register, reset).
Langue	language	locale du realm	Langue du widget ; vide pour suivre la locale Keycloak.
Bloquer en cas d'échec	fail.closed	true	Lorsque l'API CaptchaLa est injoignable, refuse la soumission. Désactivez pour passer en mode ouvert.
Utiliser le jeton serveur	use.server.token	true	Émet un jeton serveur à usage unique au rendu pour un anti-rejeu renforcé.

FAQ

Le plugin est-il gratuit ?

Oui. Le plugin Keycloak est gratuit et open source. La formule gratuite CaptchaLa couvre 10 000 vérifications par mois — les formules payantes ne s'appliquent que si vous avez besoin de plus de volume.

Quelles versions de Keycloak sont prises en charge ?

Keycloak 26+ sur la distribution Quarkus, compilé avec la version 26.5.6 et Java 17. Déposez le JAR dans providers/, lancez kc.sh build et redémarrez.

Quels écrans peut-il protéger ?

La connexion navigateur, l'auto-inscription et la réinitialisation de mot de passe. Chacun est ajouté à son flux indépendamment, vous pouvez donc en protéger un, deux ou les trois.

L'App Secret est-il un jour exposé au navigateur ?

Non. Le secret est stocké masqué et n'est envoyé que dans l'en-tête X-App-Secret de Keycloak vers l'API CaptchaLa. Il n'apparaît dans aucune page, aucun template ni aucun journal. Chaque défi est vérifié avec un jeton à usage unique, de sorte qu'un jeton résolu ne peut pas être rejoué.

Que se passe-t-il si l'API CaptchaLa est injoignable ?

Par défaut, le plugin fonctionne en mode fermé (la soumission est refusée). Désactivez fail.closed sur une exécution donnée pour passer en mode ouvert — utile pour un déploiement progressif, déconseillé en production.

Sources

• Dépôt du plugin : github.com/Captcha-La/captchala-keycloak
• Releases (JAR) : github.com/Captcha-La/captchala-keycloak/releases
• Problèmes / demandes de fonctionnalités : ouverts sur le dépôt ci-dessus
• À voir aussi : SDK Web · Référence de l'API