Keycloak

Keycloak ist ein Server, keine Seite, auf der du ein Skript einbindest, also kommt Caputchin als Keycloak-Extension: ein Provider-JAR, das du in Keycloak ablegst. Es rendert das Caputchin-Widget auf den Login-, Passwort-Reset- und Registrierungsseiten und verifiziert das Token innerhalb von Keycloak, bevor der Flow weiterläuft. Sowohl das Checkbox-Widget als auch das Spiel funktionieren.

Die Extension ist Open Source. Die vollständige Referenz (jede Konfigurationseigenschaft, das Realm-Export-JSON, der Theme-Vertrag und eine Kompatibilitätsmatrix) liegt im Repository: github.com/Caputchin/caputchin-keycloak.

1. Die Extension installieren

Bau das Provider-JAR, leg es in Keycloak ab und baue dann neu:

# 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 ist nötig, damit Keycloak die Provider findet.

2. Wähle, wie das Widget rendert

Es gibt zwei Wege, und du wählst pro Realm.

Schlüsselfertig: das mitgelieferte Theme (kein eigenes Theme nötig)

Das JAR bringt ein caputchin-Login-Theme mit. Setz es unter Realm Settings → Themes → Login theme: caputchin, und das Widget rendert auf den Login-, Reset- und Registrierungsseiten ohne Template-Bearbeitung. Das ist der schnellste Weg, wenn du einen Standard-Keycloak-Login nutzt.

Headless: dein eigenes Theme rendert das Widget

Lieferst du ein eigenes Login-Theme (zum Beispiel ein Keycloakify-React-Theme), behalt dein Theme und betreib die Extension headless. Sie legt die Widget-Konfiguration in den Seitenkontext offen und validiert das Token; dein Theme rendert das <caputchin-widget>- (oder <caputchin-game>-)Element und stylt es mit deinen Design-Tokens. Das Token-Feld ist caputchin-token. Der vollständige Attribut-Vertrag und ein Keycloakify-Beispiel stehen im Theme-Leitfaden des Repositorys.

3. An deine Flows binden

Unter Authentication → Flows dupliziere den Flow, den du schützen willst, und tausch die Execution:

Die Login- und Reset-Aufgaben rendern auf derselben Seite wie die Anmeldedaten, nicht als separater Schritt. Öffne die Konfiguration jeder Execution (das Zahnrad), um deine Keys zu setzen. Füg dem Direct-Grant-Flow keine Aufgabe hinzu: dort gibt es keinen Browser, also würde es API-Token-Anfragen brechen.

4. Die Keys konfigurieren

Setz in der Execution-Konfiguration:

• Site-Key: dein Public Key (cpt_pub_...). Der einzige Wert, der an den Browser geht.
• Secret-Key: dein Secret (cpt_sec_...). Du kannst es als Literal hinterlegen, auf eine Umgebungsvariable zeigen lassen (damit es nie in deinem Realm-Export landet) oder eine ${vault.*}-Referenz nutzen.
• Widget-Modus: checkbox, invisible oder game. Dazu Größe, Locale (folgt standardmäßig dem Realm-Locale) und Skin.
• Fail closed: standardmäßig an, sodass ein Verify-Ausfall blockt, statt Bots durchzulassen.

Den reicheren Look (welches Spiel, Skins, Marke) stellst du einmalig im Caputchin-Dashboard am Site-Key selbst ein, sodass du ihn hier nicht wiederholst.

5. Das Widget in deiner Content Security Policy erlauben

Keycloaks standardmäßige Login-CSP ist strenger, als das Widget braucht. Erlaube unter Realm Settings → Security Defenses → Content Security Policy das Loader-Skript, den Verify-Host und WebAssembly. Den exakten Wert findest du im CSP-Leitfaden des Repositorys.

Lokal ausprobieren

Das Repository enthält ein Ein-Befehl-Keycloak lokal (e2e/), verdrahtet mit einem lokalen Caputchin-Stack, sodass du dich vor dem Deploy durch alle drei geschützten Flows klicken kannst. Sieh dir das README des Repositorys an.