---
type: how-to
title: Keycloak
summary: "Sichere Keycloak-Login, Passwort-Reset und Registrierung mit Caputchin ab: installiere die Extension, wähle einen Render-Modus und verifiziere das Token serverseitig."
---

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](https://github.com/Caputchin/caputchin-keycloak).

<Callout type="info">
Funktioniert mit Keycloak 26.x (die Quarkus-Distribution). Du brauchst Zugriff auf das Keycloak-Deployment, um ein Provider-JAR hinzuzufügen und `kc.sh build` auszuführen; dies ist keine gehostete Marketplace-App.
</Callout>

## 1. Die Extension installieren

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

```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` 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](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/theme-contract.md).

## 3. An deine Flows binden

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

| Flow | Setz die Execution auf |
| --- | --- |
| Browser (login) | Caputchin Username Password Form |
| Reset Credentials | Caputchin Reset Credential - Choose User |
| Registration | füg Caputchin zum Registrierungsformular hinzu |

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](https://caputchin.com) 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](https://github.com/Caputchin/caputchin-keycloak/blob/main/docs/csp.md).

<Callout type="info">
Die serverseitige Verifizierung (Keycloak zum Verify-Host) ist ein Server-zu-Server-Aufruf und von der Browser-CSP nicht betroffen. Nur der browserseitige Widget-Verkehr ist es.
</Callout>

## 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](https://github.com/Caputchin/caputchin-keycloak) an.