Keycloak

Keycloak ist ein Server, keine Seite, auf der du ein Script einbindest, also kommt Caputchin als Keycloak-Extension: ein Provider-JAR, das du zu Keycloak hinzufügst. 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. Rechne mit etwa 15 Minuten vom neuen Konto bis zur ersten serverseitig verifizierten Session.

1. Einen Site-Key erstellen

Melde dich unter caputchin.com/login an (deine erste Anmeldung legt das Konto an), öffne dein Team Persönlich, klick auf Site-Key erstellen, benenn ihn nach deinem Keycloak-Realm und klick auf Erstellen. Kopier beide Werte:

• Öffentlicher Schlüssel (cpt_pub_...),
• Secret (cpt_sec_...). Es wird nur einmal angezeigt.

Konto und ersten Site-Key erstellen geht dieselben Bildschirme ausführlicher durch.

2. Die Extension installieren

Lade caputchin-keycloak.jar aus dem neuesten Release herunter, kopier es in das Verzeichnis providers/ von Keycloak und bau neu:

cp 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. In einem Container-Image kopierst du das JAR und führst den Build im Image aus:

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

Willst du das JAR stattdessen aus dem Quellcode bauen, sieh dir den Installationsleitfaden des Repositorys an.

3. Keycloak das Secret geben

Halt das Secret aus der Realm-Konfiguration heraus: Setz es als Umgebungsvariable auf dem Keycloak-Server, zum Beispiel CAPUTCHIN_SECRET, und starte Keycloak neu. In Schritt 5 trägst du nur den Namen der Variable ein. Ein Secret als Literal oder eine ${vault.*}-Referenz funktioniert auch; sieh dir den Konfigurationsleitfaden des Repositorys an.

4. Wählen, wie das Widget rendert

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

Schlüsselfertig: das mitgelieferte Theme

Das JAR bringt ein caputchin-Login-Theme mit. Öffne in der Admin Console deinen Realm, geh auf Realm settings → Themes, setz Login theme auf caputchin und klick auf Save. 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 aus (zum Beispiel ein Keycloakify-React-Theme), behalt dein Theme und betreib die Extension headless. Sie legt die Widget-Konfiguration im Seitenkontext offen und validiert das Token; dein Theme rendert das <caputchin-widget>- (oder <caputchin-game>-)Element. Das Token-Feld ist caputchin-token. Der vollständige Attribut-Vertrag und ein Keycloakify-Beispiel stehen im Theme-Leitfaden des Repositorys.

5. An den Login-Flow binden

Keycloak ändert den Authenticator eines Schritts nicht an Ort und Stelle, also fügst du den Caputchin-Schritt einer Kopie des Flows hinzu und entfernst den ursprünglichen Schritt.

1. Geh auf Authentication. Öffne beim Flow browser das Menü (⋮), klick auf Duplicate, benenn die Kopie (zum Beispiel browser caputchin) und klick auf Duplicate.

2. Such in der Kopie den Sub-Flow forms. Klick auf seinen Button + (Add), wähl Add execution, wähl Caputchin Username Password Form und klick auf Add.

3. Zieh den neuen Schritt ganz nach oben in den Sub-Flow forms, über den Sub-Flow Conditional 2FA, damit er dort läuft, wo der alte Schritt lief. Seine Anforderung ist Required.

4. Lösch den ursprünglichen Schritt Username Password Form aus dem Sub-Flow forms.

5. Klick auf das Zahnrad (Settings) am Caputchin-Schritt und füll aus:

   • Alias: ein beliebiger Name, etwa caputchin-login.
   • Site key: dein öffentlicher Schlüssel (cpt_pub_...), der einzige Wert, der an den Browser geht.
   • Secret key env var: der Variablenname aus Schritt 3, etwa CAPUTCHIN_SECRET.

   Klick dann auf Save. Die übrigen Felder haben funktionierende Standardwerte: Widget mode checkbox (oder invisible oder game), Locale kc (folgt dem Realm-Locale) und Fail closed an, sodass ein Verify-Ausfall Anmeldungen blockt, statt sie durchzulassen.

6. Öffne das Menü Action des Flows, klick auf Bind flow, behalt Browser flow und klick auf Save.

Die Aufgabe rendert auf derselben Seite wie die Anmeldedaten, nicht als separater Schritt. Mit den Standardeinstellungen läuft die Prüfung, wenn der Nutzer auf Sign In klickt.

Passwort-Reset und Registrierung

Dasselbe Muster schützt die beiden anderen Formulare:

Jeder Caputchin-Schritt hat seine eigenen Einstellungen (Zahnrad), trag den Site-Key und die Secret-Variable also bei jedem ein. Füg dem Direct-Grant-Flow keine Aufgabe hinzu: Dort gibt es keinen Browser, also würde es API-Token-Anfragen brechen. An Flows binden im Repository zeigt dieselbe Einrichtung als Realm-Export-JSON.

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

6. Die Content Security Policy prüfen

Keycloaks standardmäßige Login-Content-Security-Policy (unter Realm settings → Security defenses → Headers) ist frame-src 'self'; frame-ancestors 'self'; object-src 'none';. Sie beschränkt Frames, nicht Scripts oder Verbindungen, und das Spiel läuft in einem srcdoc-Frame, also funktionieren die Checkbox, das unsichtbare Widget und das Spiel damit alle unverändert.

Setzt du eine eigene, strengere Policy, geh von der im CSP-Leitfaden des Repositorys aus. Eine script-src-Direktive gilt auch für Keycloaks eigene Inline-Scripts, teste also nach jeder Änderung die Login-Seite und die Account Console.

Die serverseitige Verifizierung (Keycloak zum Verify-Host) ist ein Server-zu-Server-Aufruf und von der Browser-Policy nicht betroffen.

7. Die erste serverseitig verifizierte Session bestätigen

1. Öffne den Login deiner Anwendung (oder die Login-Seite des Realms) in einem privaten Fenster.
2. Melde dich mit einem Testnutzer an. Das Widget läuft, wenn du auf Sign In klickst, und Keycloak meldet dich an.
3. Öffne im Caputchin-Dashboard dein Team und klick auf deinen Site-Key. Aktualisier die Statistik.

Serverseitig verifiziert zeigt jetzt mindestens 1: Keycloak hat ein Token bei Caputchin bestätigt. Das ist deine erste verifizierte Session. Zeigt die Login-Seite "Verification failed. Please complete the check and try again." und bleibt Serverseitig verifiziert bei 0, hat das Token Keycloak nie erreicht: Prüf die Browser-Konsole auf einen Content-Security-Policy-Fehler (Schritt 6). Ist Im Browser bestanden gestiegen, die Anmeldung schlägt aber trotzdem fehl, prüf, ob die Secret-Variable aus Schritt 3 auf dem Server gesetzt ist. Statistik und Sessions erklärt jede Zahl.

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.

Siehe auch

• Site-Keys im Überblick
• WordPress