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 ajoutes à 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. Compte environ 15 minutes entre un nouveau compte et la première session vérifiée côté serveur.

1. Crée une clé de site

Connecte-toi sur caputchin.com/login (ta première connexion crée le compte), ouvre ton équipe Personnelle, clique sur Créer une clé de site, donne-lui le nom de ton realm Keycloak et clique sur Créer. Copie les deux valeurs :

• Clé publique (cpt_pub_...),
• Secret (cpt_sec_...). Il n'est affiché qu'une seule fois.

Crée ton compte et ta première clé de site parcourt les mêmes écrans plus en détail.

2. Installe l'extension

Télécharge caputchin-keycloak.jar depuis la dernière version, copie-le dans le répertoire providers/ de Keycloak et reconstruis :

cp 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. Dans une image de conteneur, copie le JAR et lance le build dans l'image :

FROM quay.io/keycloak/keycloak:26.4
COPY caputchin-keycloak.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build

Pour construire plutôt le JAR depuis les sources, vois le guide d'installation du dépôt.

3. Donne le secret à Keycloak

Garde le secret hors de la configuration du realm : définis-le comme variable d'environnement sur le serveur Keycloak, par exemple CAPUTCHIN_SECRET, et redémarre Keycloak. À l'étape 5, tu ne saisis que le nom de la variable. Un secret en littéral ou une référence ${vault.*} fonctionne aussi ; vois le guide de configuration du dépôt.

4. Choisis comment le widget se rend

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

Clé en main : le theme fourni

Le JAR fournit un theme de login caputchin. Dans l'Admin Console, ouvre ton realm, va dans Realm settings → Themes, mets Login theme sur caputchin et clique sur Save. 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>). 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.

5. Lie-la au flux de login

Keycloak ne change pas l'authentificateur d'une étape sur place, donc tu ajoutes l'étape Caputchin à une copie du flux et tu retires l'étape d'origine.

1. Va dans Authentication. Sur le flux browser, ouvre le menu (⋮), clique sur Duplicate, nomme la copie (par exemple browser caputchin) et clique sur Duplicate.

2. Dans la copie, trouve le sous-flux forms. Clique sur son bouton + (Add), choisis Add execution, sélectionne Caputchin Username Password Form et clique sur Add.

3. Fais glisser la nouvelle étape tout en haut du sous-flux forms, au-dessus du sous-flux Conditional 2FA, pour qu'elle s'exécute là où s'exécutait l'ancienne étape. Son exigence est Required.

4. Supprime l'étape d'origine Username Password Form du sous-flux forms.

5. Clique sur l'engrenage (Settings) de l'étape Caputchin et remplis :

   • Alias : n'importe quel nom, comme caputchin-login.
   • Site key : ta clé publique (cpt_pub_...), la seule valeur envoyée au navigateur.
   • Secret key env var : le nom de la variable de l'étape 3, comme CAPUTCHIN_SECRET.

   Puis clique sur Save. Les autres champs ont des valeurs par défaut qui fonctionnent : Widget mode checkbox (ou invisible, ou game), Locale kc (suit le locale du realm) et Fail closed activé, de sorte qu'une panne de vérification bloque les connexions au lieu de les laisser passer.

6. Ouvre le menu Action du flux, clique sur Bind flow, garde Browser flow et clique sur Save.

Le défi se rend sur la même page que les identifiants, pas comme une étape à part. Avec les réglages par défaut, le contrôle s'exécute quand l'utilisateur clique sur Sign In.

Réinitialisation de mot de passe et inscription

Le même schéma protège les deux autres formulaires :

Chaque étape Caputchin a ses propres réglages (engrenage), donc saisis la clé de site et la variable du secret sur chacune. N'ajoute pas de défi au flux de direct grant : il n'y a pas de navigateur là, donc ça casserait les requêtes de token par API. Lier aux flux dans le dépôt montre la même configuration en JSON d'export de realm.

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 dans Keycloak.

6. Vérifie la Content Security Policy

La Content Security Policy de login par défaut de Keycloak (sous Realm settings → Security defenses → Headers) est frame-src 'self'; frame-ancestors 'self'; object-src 'none';. Elle restreint les frames, pas les scripts ni les connexions, et le jeu s'exécute dans une frame srcdoc, donc la case à cocher, le widget invisible et le jeu fonctionnent tous avec elle sans changement.

Si tu définis ta propre politique plus stricte, pars de celle du guide CSP du dépôt. Une directive script-src s'applique aussi aux scripts inline de Keycloak lui-même, alors teste la page de login et l'Account Console après chaque changement.

La vérification côté serveur (de Keycloak vers l'hôte de vérification) est un appel de serveur à serveur et n'est pas affectée par la politique du navigateur.

7. Confirme la première session vérifiée côté serveur

1. Ouvre le login de ton application (ou la page de login du realm) dans une fenêtre privée.
2. Connecte-toi avec un utilisateur de test. Le widget s'exécute quand tu cliques sur Sign In, et Keycloak te connecte.
3. Dans le tableau de bord Caputchin, ouvre ton équipe et clique sur ta clé de site. Actualise les statistiques.

Vérifiées côté serveur affiche maintenant au moins 1 : Keycloak a confirmé un token auprès de Caputchin. C'est ta première session vérifiée. Si la page de login affiche "Verification failed. Please complete the check and try again." et que Vérifiées côté serveur reste à 0, le token n'a jamais atteint Keycloak : cherche une erreur de Content Security Policy dans la console du navigateur (étape 6). Si Réussies dans le navigateur a augmenté mais que la connexion échoue quand même, vérifie que la variable du secret de l'étape 3 est définie sur le serveur. Statistiques et sessions explique chaque chiffre.

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.

Voir aussi

• Vue d'ensemble des clés de site
• WordPress