Keycloak

Plugin Keycloak rasmi CaptchaLa. Menambah cabaran CAPTCHA pada skrin log masuk, pendaftaran dan tetapan semula kata laluan terbina dalam Keycloak, disahkan di sebelah pelayan, tanpa menulis sebarang kod. Dihantar sebagai satu JAR pembekal yang anda letakkan ke dalam Keycloak.

Apa yang dilindungi

Setiap aliran di bawah diwayarkan sebagai langkah pengesahan berasingan — anda hanya melindungi skrin yang dikehendaki.

• Log masuk penyemak imbas (borang nama pengguna / kata laluan)
• Pendaftaran sendiri
• Tetapan semula kata laluan (skrin "lupa kata laluan")

Cabaran dipaparkan sebagai widget terapung secara lalai (float), atau sebagai modal klik-untuk-buka (popup).

Pasang

1. Dapatkan JAR

Plugin ini sumber terbuka di github.com/Captcha-La/captchala-keycloak. Dua pilihan:

• Muat turun keluaran (disyorkan) — ambil keycloak-captchala-<version>.jar dari halaman Releases repositori.
• Bina dari sumber — git clone repositori dan jalankan mvn clean package; JAR dihasilkan di bawah target/.

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

2. Sebarkan

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

Kemudian tetapkan tema log masuk: Realm settings → Themes → Login theme → captchala.

3. Dapatkan kunci anda

Daftar di dash.captcha.la, cipta aplikasi, kemudian salin:

• App Key — kunci awam, dibenamkan dalam halaman
• App Secret — sebelah pelayan sahaja, digunakan oleh Keycloak untuk mencipta token sekali guna dan memanggil /v1/validate

4. Sambungkan aliran

Dalam konsol admin, tambah pelaksanaan yang sepadan ke setiap aliran yang ingin dilindungi, kemudian klik ikon gear untuk menampal App Key dan App Secret anda:

• Log masuk penyemak imbas — duplikasi aliran browser, gantikan Username Password Form dengan Captchala Username Password Form (REQUIRED), ikat sebagai aliran browser realm.
• Pendaftaran — duplikasi aliran registration, tambah Captchala Registration (REQUIRED) ke sub-aliran registration-form, ikat sebagai aliran pendaftaran realm.
• Tetapan semula kata laluan — duplikasi aliran reset credentials, gantikan Choose User dengan Captchala Reset Credential (choose user) (REQUIRED), ikat sebagai aliran reset-credentials realm.

Buka salah satu skrin yang dilindungi dalam tetingkap peribadi untuk mengesahkan cabaran dipaparkan.

Konfigurasi

Setiap pelaksanaan dikonfigurasi secara berasingan dari ikon gear-nya. Lalai berfungsi terus setelah kunci ditetapkan.

Tetapan	Kunci	Lalai	Penerangan
App Key	app.key	—	Kunci awam dari papan pemuka CaptchaLa. Wajib.
App Secret	app.secret	—	Rahsia pelayan. Wajib. Disimpan bertopeng, tidak pernah didedahkan kepada penyemak imbas.
URL asas API	api.base	https://apiv1.captcha.la	Asas API CaptchaLa.
URL skrip widget	script.url	https://api.captcha.la/sdk/jslib/captchala.js	Tempat JS widget dimuatkan.
URL CSS widget	css.url	https://api.captcha.la/sdk/jslib/captchala.css	Tempat CSS widget dimuatkan.
Mod render	product	float	float (widget terapung) atau popup (modal).
Label aksi	action	mengikut aliran	action yang dihantar semasa pengesahan (login, register, reset).
Bahasa	language	lokal realm	Bahasa widget; kosong mengikut lokal Keycloak.
Gagal tertutup	fail.closed	true	Apabila API CaptchaLa tidak dapat dicapai, tolak penyerahan. Matikan untuk gagal terbuka.
Guna token pelayan	use.server.token	true	Cipta token pelayan sekali guna semasa render untuk anti-ulang main yang lebih kukuh.

Soalan lazim

Adakah plugin ini percuma?

Ya. Plugin Keycloak ini percuma dan sumber terbuka. Pelan percuma CaptchaLa merangkumi 10,000 pengesahan sebulan — pelan berbayar hanya berkenaan jika anda perlukan volum lebih tinggi.

Versi Keycloak mana yang disokong?

Keycloak 26+ pada pengedaran Quarkus, dibina terhadap 26.5.6 dengan Java 17. Letakkan JAR ke dalam providers/, jalankan kc.sh build, dan mulakan semula.

Skrin mana yang boleh dilindungi?

Log masuk penyemak imbas, pendaftaran sendiri, dan tetapan semula kata laluan. Setiap satu ditambah ke aliran secara berasingan, jadi anda boleh melindungi satu, dua, atau ketiga-tiganya.

Adakah App Secret pernah didedahkan kepada penyemak imbas?

Tidak. Rahsia disimpan bertopeng dan hanya dihantar dalam pengepala X-App-Secret dari Keycloak ke API CaptchaLa. Ia tidak pernah muncul dalam mana-mana halaman, templat, atau log. Setiap cabaran disahkan dengan token sekali guna, jadi token yang diselesaikan tidak boleh diulang main.

Apa yang berlaku jika API CaptchaLa tidak dapat dicapai?

Secara lalai plugin gagal tertutup (penyerahan ditolak). Tetapkan fail.closed kepada mati pada mana-mana pelaksanaan untuk gagal terbuka sebagai gantinya — berguna untuk pelancaran berperingkat, tidak disyorkan untuk pengeluaran.

Sumber

• Repositori plugin: github.com/Captcha-La/captchala-keycloak
• Keluaran (JAR): github.com/Captcha-La/captchala-keycloak/releases
• Isu / permintaan ciri: fail terhadap repositori di atas
• Berkaitan: Web SDK · Rujukan API