Keycloak

Keycloak adalah sebuah server, bukan halaman tempat kamu menyematkan skrip, jadi Caputchin hadir sebagai sebuah extension Keycloak: sebuah JAR provider yang kamu tambahkan ke 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) ada di repositori: github.com/Caputchin/caputchin-keycloak. Siapkan sekitar 15 menit dari akun baru sampai sesi terverifikasi server pertama.

1. Buat kunci situs

Masuk di caputchin.com/login (login pertamamu sekaligus membuat akun), buka tim Pribadi-mu, klik Buat kunci situs, beri nama sesuai realm Keycloak-mu, lalu klik Buat. Salin kedua nilainya:

• kunci publik (cpt_pub_...),
• rahasia (cpt_sec_...). Nilai ini hanya ditampilkan sekali.

Buat akun dan kunci situs pertamamu memandu layar yang sama dengan lebih rinci.

2. Pasang extension-nya

Unduh caputchin-keycloak.jar dari rilis terbaru, salin ke direktori providers/ Keycloak, lalu bangun ulang:

cp 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. Di image container, salin JAR-nya dan jalankan build di dalam image:

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

Untuk membangun JAR dari kode sumber, lihat panduan instalasi repositori.

3. Berikan rahasianya ke Keycloak

Jauhkan rahasia dari konfigurasi realm: setel sebagai variabel lingkungan di server Keycloak, misalnya CAPUTCHIN_SECRET, lalu mulai ulang Keycloak. Di langkah 5 kamu hanya memasukkan nama variabelnya. Rahasia literal atau referensi ${vault.*} juga bisa; lihat panduan konfigurasi repositori.

4. Pilih cara widget merender

Ada dua cara, dan kamu memilih per realm.

Siap pakai: theme bawaan

JAR-nya membawa sebuah theme login caputchin. Di Admin Console, buka realm-mu, masuk ke Realm settings → Themes, setel Login theme ke caputchin, lalu klik Save. 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>). Field token-nya adalah caputchin-token. Kontrak atribut lengkap dan sebuah contoh Keycloakify ada di panduan theme repositori.

5. Ikat ke alur login

Keycloak tak mengganti authenticator sebuah langkah di tempat, jadi kamu menambahkan langkah Caputchin ke salinan alurnya dan menghapus langkah aslinya.

1. Buka Authentication. Di alur browser, buka menunya (⋮), klik Duplicate, beri nama salinannya (misalnya browser caputchin), lalu klik Duplicate.

2. Di salinan itu, cari sub-alur forms. Klik tombol + (Add) miliknya, pilih Add execution, pilih Caputchin Username Password Form, lalu klik Add.

3. Seret langkah baru itu ke paling atas sub-alur forms, di atas sub-alur Conditional 2FA, agar ia berjalan di tempat langkah lama berjalan. Persyaratannya adalah Required.

4. Hapus langkah asli Username Password Form dari sub-alur forms.

5. Klik roda gigi (Settings) di langkah Caputchin dan isi:

   • Alias: nama apa saja, misalnya caputchin-login.
   • Site key: kunci publikmu (cpt_pub_...), satu-satunya nilai yang dikirim ke peramban.
   • Secret key env var: nama variabel dari langkah 3, misalnya CAPUTCHIN_SECRET.

   Lalu klik Save. Field lainnya punya nilai bawaan yang langsung jalan: Widget mode checkbox (atau invisible, atau game), Locale kc (mengikuti locale realm), dan Fail closed menyala, jadi gangguan verifikasi memblokir login alih-alih meloloskannya.

6. Buka menu Action alur itu, klik Bind flow, biarkan Browser flow, lalu klik Save.

Tantangannya merender di halaman yang sama dengan kredensial, bukan sebagai langkah terpisah. Dengan pengaturan bawaan, pemeriksaan berjalan saat pengguna mengklik Sign In.

Reset kata sandi dan registrasi

Pola yang sama melindungi dua formulir lainnya:

Setiap langkah Caputchin punya pengaturannya sendiri (roda gigi), jadi masukkan kunci situs dan variabel rahasia di masing-masing. Jangan menambahkan tantangan ke alur direct grant: di sana tak ada peramban, jadi itu akan merusak permintaan token via API. Mengikat ke alur di repositori menunjukkan penyiapan yang sama sebagai JSON ekspor realm.

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

6. Periksa Content Security Policy

Content Security Policy login bawaan Keycloak (di Realm settings → Security defenses → Headers) adalah frame-src 'self'; frame-ancestors 'self'; object-src 'none';. Kebijakan ini membatasi frame, bukan skrip atau koneksi, dan game berjalan di frame srcdoc, jadi checkbox, widget tak terlihat, dan game semuanya jalan dengannya tanpa diubah.

Jika kamu menyetel kebijakan sendiri yang lebih ketat, mulailah dari yang ada di panduan CSP repositori. Direktif script-src juga berlaku untuk skrip inline milik Keycloak sendiri, jadi uji halaman login dan Account Console setelah setiap perubahan.

Verifikasi di sisi server (Keycloak ke host verifikasi) adalah panggilan server-ke-server dan tak terpengaruh kebijakan peramban.

7. Pastikan sesi terverifikasi server pertama

1. Buka login aplikasimu (atau halaman login realm) di jendela privat.
2. Login dengan pengguna uji. Widget berjalan saat kamu mengklik Sign In, dan Keycloak meloloskanmu masuk.
3. Di dasbor Caputchin, buka tim-mu dan klik kunci situsmu. Muat ulang statistiknya.

Terverifikasi server kini menunjukkan setidaknya 1: Keycloak memastikan sebuah token dengan Caputchin. Itulah sesi terverifikasi pertamamu. Jika halaman login menampilkan "Verification failed. Please complete the check and try again." dan Terverifikasi server tetap di 0, berarti token-nya tak pernah sampai ke Keycloak: periksa konsol peramban untuk galat Content Security Policy (langkah 6). Jika Selesai di klien naik tapi login tetap gagal, pastikan variabel rahasia dari langkah 3 sudah disetel di server. Statistik dan sesi menjelaskan setiap angkanya.

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.

Lihat juga

• Ikhtisar kunci situs
• WordPress