Keycloak

Keycloak est un serveur, pas une page sur laquelle tu intègres un script, donc Caputchin se livre comme une extension Keycloak : un JAR de fournisseur que tu déposes dans Keycloak. Il rend le widget Caputchin sur les pages de login, de réinitialisation de mot de passe et d'inscription, et vérifie le token depuis l'intérieur de Keycloak avant que le flux ne continue. Le widget à case à cocher et le jeu fonctionnent tous deux.

L'extension est open source. La référence complète (chaque propriété de configuration, le JSON d'export du realm, le contrat de theme et une matrice de compatibilité) vit dans le dépôt : github.com/Caputchin/caputchin-keycloak.

1. Installe l'extension

Construis le JAR de fournisseur et place-le dans Keycloak, puis reconstruis :

# build (no JDK on the host? run it in Docker)
docker run --rm -v "$PWD":/work -w /work maven:3.9-eclipse-temurin-21 mvn -DskipTests package

cp target/caputchin-keycloak.jar "$KEYCLOAK_HOME/providers/"
"$KEYCLOAK_HOME/bin/kc.sh" build
"$KEYCLOAK_HOME/bin/kc.sh" start --optimized

kc.sh build est requis pour que Keycloak découvre les fournisseurs.

2. Choisis comment le widget se rend

Il y a deux façons, et tu choisis par realm.

Clé en main : le theme fourni (pas de theme personnalisé nécessaire)

Le JAR fournit un theme de login caputchin. Mets-le sous Realm Settings → Themes → Login theme: caputchin, et le widget se rend sur les pages de login, de réinitialisation et d'inscription sans édition de template. C'est la voie la plus rapide si tu utilises un login Keycloak standard.

Headless : ton propre theme rend le widget

Si tu livres un theme de login personnalisé (par exemple un theme React Keycloakify), garde ton theme et fais tourner l'extension en headless. Elle expose la configuration du widget dans le contexte de la page et valide le token ; ton theme rend l'élément <caputchin-widget> (ou <caputchin-game>) et le stylise avec tes design tokens. Le champ du token est caputchin-token. Le contrat d'attributs complet et un exemple Keycloakify sont dans le guide de theme du dépôt.

3. Lie-la à tes flux

Sous Authentication → Flows, duplique le flux que tu veux protéger et échange l'exécution :

Les épreuves de login et de réinitialisation se rendent sur la même page que les identifiants, pas comme une étape à part. Ouvre la configuration de chaque exécution (l'engrenage) pour mettre tes clés. N'ajoute pas d'épreuve au flux de direct grant : il n'y a pas de navigateur là, donc ça casserait les requêtes de token par API.

4. Configure les clés

Dans la configuration de l'exécution, mets :

• Clé de site : ta clé publique (cpt_pub_...). La seule valeur envoyée au navigateur.
• Clé secrète : ton secret (cpt_sec_...). Tu peux la stocker en littéral, pointer vers une variable d'environnement (pour qu'elle n'atterrisse jamais dans ton export de realm), ou utiliser une référence ${vault.*}.
• Mode du widget : checkbox, invisible ou game. Plus la taille, le locale (suit par défaut le locale du realm) et le skin.
• Fail closed : activé par défaut, de sorte qu'une panne de vérification bloque plutôt que de laisser passer les bots.

Le look plus riche (quel jeu, skins, marque) se règle une seule fois dans le tableau de bord Caputchin sur la clé de site elle-même, donc tu ne le répètes pas ici.

5. Autorise le widget dans ta Content Security Policy

La CSP de login par défaut de Keycloak est plus stricte que ce dont le widget a besoin. Sous Realm Settings → Security Defenses → Content Security Policy, autorise le script du chargeur, l'hôte de vérification et WebAssembly. La valeur exacte est dans le guide CSP du dépôt.

Essaie-le en local

Le dépôt inclut un Keycloak local en une commande (e2e/) câblé à un stack Caputchin local, pour que tu puisses cliquer à travers les trois flux protégés avant de déployer. Vois le README du dépôt.