---
type: how-to
title: Keycloak
summary: "Protège le login, la réinitialisation de mot de passe et l'inscription Keycloak avec Caputchin : installe l'extension, choisis un mode de rendu et vérifie le token côté serveur."
---
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](https://github.com/Caputchin/caputchin-keycloak).
Fonctionne avec Keycloak 26.x (la distribution Quarkus). Tu as besoin d'un accès au déploiement Keycloak pour ajouter un JAR de fournisseur et lancer `kc.sh build` ; ce n'est pas une app de marketplace hébergée.
## 1. Installe l'extension
Construis le JAR de fournisseur et place-le dans Keycloak, puis reconstruis :
```bash
# 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 `` (ou ``) 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](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/theme-contract.md).
## 3. Lie-la à tes flux
Sous **Authentication → Flows**, duplique le flux que tu veux protéger et échange l'exécution :
| Flux | Mets l'exécution sur |
| --- | --- |
| Browser (login) | Caputchin Username Password Form |
| Reset Credentials | Caputchin Reset Credential - Choose User |
| Registration | ajoute Caputchin au formulaire d'inscription |
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](https://caputchin.com) 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](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/csp.md).
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 CSP du navigateur. Seul le trafic du widget côté navigateur l'est.
## 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](https://github.com/Caputchin/caputchin-keycloak).