Keycloak

Keycloak adalah sebuah server, bukan halaman tempat kamu menyematkan skrip, jadi Caputchin hadir sebagai sebuah extension Keycloak: sebuah JAR provider yang kamu jatuhkan ke dalam Keycloak. Ia merender widget Caputchin di halaman login, reset kata sandi, dan registrasi, lalu memverifikasi token dari dalam Keycloak sebelum alurnya berlanjut. Baik widget checkbox maupun game-nya sama-sama jalan.

Extension-nya bersumber terbuka. Referensi lengkapnya (setiap properti konfigurasi, JSON ekspor realm, kontrak theme, dan matriks kompatibilitas) hidup di repositori: github.com/Caputchin/caputchin-keycloak.

1. Pasang extension-nya

Bangun JAR provider dan taruh di Keycloak, lalu bangun ulang:

# 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 wajib agar Keycloak menemukan provider-providernya.

2. Pilih cara widget merender

Ada dua cara, dan kamu memilih per realm.

Siap pakai: theme bawaan (tanpa theme kustom)

JAR-nya membawa sebuah theme login caputchin. Setel di Realm Settings → Themes → Login theme: caputchin, dan widget merender di halaman login, reset, dan registrasi tanpa menyunting template. Ini jalur tercepat kalau kamu memakai login Keycloak standar.

Headless: theme-mu sendiri yang merender widget

Kalau kamu mengirim theme login kustom (misalnya theme React Keycloakify), pertahankan theme-mu dan jalankan extension secara headless. Ia membuka konfigurasi widget ke konteks halaman dan memvalidasi token; theme-mu merender elemen <caputchin-widget> (atau <caputchin-game>) dan menatanya dengan design token-mu. Field token-nya adalah caputchin-token. Kontrak atribut lengkap dan sebuah contoh Keycloakify ada di panduan theme repositori.

3. Ikat ke alurmu

Di Authentication → Flows, gandakan alur yang ingin kamu lindungi dan tukar eksekusinya:

Tantangan login dan reset merender di halaman yang sama dengan kredensial, bukan sebagai langkah terpisah. Buka konfigurasi tiap eksekusi (roda giginya) untuk menyetel kunci-kuncimu. Jangan menambahkan tantangan ke alur direct grant: di sana tak ada peramban, jadi itu akan merusak permintaan token via API.

4. Konfigurasikan kuncinya

Di konfigurasi eksekusi, setel:

• Kunci situs: public key-mu (cpt_pub_...). Satu-satunya nilai yang dikirim ke peramban.
• Kunci rahasia: secret-mu (cpt_sec_...). Kamu bisa menyimpannya sebagai literal, mengarahkan ke variabel lingkungan (agar tak pernah masuk ke ekspor realm-mu), atau memakai referensi ${vault.*}.
• Mode widget: checkbox, invisible, atau game. Plus ukuran, locale (default mengikuti locale realm), dan skin.
• Fail closed: menyala secara baku, jadi gangguan verifikasi memblokir alih-alih membiarkan bot lewat.

Tampilan yang lebih kaya (game mana, skin, merek) disetel sekali saja di dasbor Caputchin pada kunci situs itu sendiri, jadi kamu tak mengulanginya di sini.

5. Izinkan widget di Content Security Policy-mu

CSP login bawaan Keycloak lebih ketat dari yang widget butuhkan. Di Realm Settings → Security Defenses → Content Security Policy, izinkan skrip loader, host verifikasi, dan WebAssembly. Nilai persisnya ada di panduan CSP repositori.

Coba secara lokal

Repositori menyertakan sebuah Keycloak lokal satu perintah (e2e/) yang terhubung ke stack Caputchin lokal, agar kamu bisa mengeklik ketiga alur tergerbang sebelum men-deploy. Lihat README repositori.