--- title: Keycloak --- # 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**](https://github.com/Captcha-La/captchala-keycloak). Deux options : - **Télécharger la release** (recommandé) — récupérez `keycloak-captchala-.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 ```bash 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`](https://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`](https://github.com/Captcha-La/captchala-keycloak) - Releases (JAR) : [`github.com/Captcha-La/captchala-keycloak/releases`](https://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](/fr/web-sdk) · [Référence de l'API](/fr/api-reference)