Keycloak

Plugin Keycloak resmi CaptchaLa. Menambahkan tantangan CAPTCHA ke layar login, pendaftaran, dan reset password bawaan Keycloak, diverifikasi di sisi server, tanpa menulis kode apa pun. Dikirimkan sebagai satu provider JAR yang Anda letakkan ke dalam Keycloak.

Cakupan

Setiap alur di bawah ini dihubungkan sebagai langkah autentikasi terpisah — Anda hanya melindungi layar yang diinginkan.

• Login browser (formulir username / password)
• Pendaftaran mandiri
• Reset password (layar "lupa password")

Tantangan ditampilkan sebagai widget mengambang secara default (float), atau sebagai modal klik-untuk-buka (popup).

Instalasi

1. Dapatkan JAR

Plugin ini bersumber terbuka di github.com/Captcha-La/captchala-keycloak. Dua opsi:

• Unduh rilis (disarankan) — ambil keycloak-captchala-<version>.jar dari halaman Releases repositori.
• Build dari sumber — git clone repo lalu jalankan mvn clean package; JAR dihasilkan di bawah target/.

Plugin ini menargetkan Keycloak ≥ 26 (Quarkus) dan Java 17.

2. Deploy

cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# restart Keycloak

Kemudian atur tema login: Realm settings → Themes → Login theme → captchala.

3. Dapatkan kunci Anda

Daftar di dash.captcha.la, buat aplikasi, lalu salin:

• App Key — kunci publik, disematkan di halaman
• App Secret — hanya sisi server, digunakan oleh Keycloak untuk mencetak token sekali pakai dan memanggil /v1/validate

4. Hubungkan alur

Di konsol admin, tambahkan eksekusi yang sesuai ke setiap alur yang ingin dilindungi, lalu klik ikon roda gigi untuk menempel App Key dan App Secret Anda:

• Login browser — duplikat alur browser, ganti Username Password Form dengan Captchala Username Password Form (REQUIRED), ikat sebagai alur browser realm.
• Pendaftaran — duplikat alur registration, tambahkan Captchala Registration (REQUIRED) ke sub-alur registration-form, ikat sebagai alur pendaftaran realm.
• Reset password — duplikat alur reset credentials, ganti Choose User dengan Captchala Reset Credential (choose user) (REQUIRED), ikat sebagai alur reset-credentials realm.

Buka salah satu layar yang dilindungi di jendela private untuk memastikan tantangan tampil dengan benar.

Konfigurasi

Setiap eksekusi dikonfigurasi secara terpisah dari ikon roda giginya. Default sudah berfungsi langsung setelah kunci diatur.

Pengaturan	Key	Default	Deskripsi
App Key	app.key	—	Kunci publik dari dasbor CaptchaLa. Wajib.
App Secret	app.secret	—	Rahasia server. Wajib. Disimpan tersamar, tidak pernah diekspos ke browser.
URL API dasar	api.base	https://apiv1.captcha.la	Base URL API CaptchaLa.
URL skrip widget	script.url	https://api.captcha.la/sdk/jslib/captchala.js	Lokasi pemuatan JS widget.
URL CSS widget	css.url	https://api.captcha.la/sdk/jslib/captchala.css	Lokasi pemuatan CSS widget.
Mode render	product	float	float (widget mengambang) atau popup (modal).
Label action	action	per alur	action yang dikirim saat validasi (login, register, reset).
Bahasa	language	lokal realm	Bahasa widget; kosong mengikuti lokal Keycloak.
Fail closed	fail.closed	true	Saat API CaptchaLa tidak dapat dijangkau, tolak pengiriman. Nonaktifkan untuk fail open.
Use server token	use.server.token	true	Cetak token server sekali pakai saat render untuk perlindungan anti-replay yang lebih kuat.

FAQ

Apakah plugin ini gratis?

Ya. Plugin Keycloak ini gratis dan bersumber terbuka. Paket gratis CaptchaLa mencakup 10.000 verifikasi per bulan — paket berbayar hanya berlaku jika Anda butuh volume lebih besar.

Versi Keycloak mana yang didukung?

Keycloak 26+ pada distribusi Quarkus, dibangun terhadap 26.5.6 dengan Java 17. Letakkan JAR ke providers/, jalankan kc.sh build, dan restart.

Layar mana yang dapat dilindungi?

Login browser, pendaftaran mandiri, dan reset password. Setiap alur ditambahkan secara terpisah, sehingga Anda dapat melindungi satu, dua, atau ketiganya.

Apakah App Secret pernah diekspos ke browser?

Tidak. Rahasia disimpan tersamar dan hanya pernah dikirim di header X-App-Secret dari Keycloak ke API CaptchaLa. Tidak pernah muncul di halaman, template, maupun log apa pun. Setiap tantangan diverifikasi dengan token sekali pakai, sehingga token yang sudah diselesaikan tidak dapat diputar ulang.

Apa yang terjadi jika API CaptchaLa tidak dapat dijangkau?

Secara default plugin gagal tertutup (pengiriman ditolak). Atur fail.closed ke nonaktif pada eksekusi mana pun untuk fail open sebagai gantinya — berguna untuk peluncuran bertahap, tidak disarankan untuk production.

Sumber

• Repositori plugin: github.com/Captcha-La/captchala-keycloak
• Rilis (JAR): github.com/Captcha-La/captchala-keycloak/releases
• Isu / permintaan fitur: diajukan ke repositori di atas
• Terkait: Web SDK · Referensi API