Keycloak

Keycloak için resmi CaptchaLa eklentisi. Keycloak'ın yerleşik giriş, kayıt ve parola sıfırlama ekranlarına kod yazmadan CAPTCHA doğrulaması ekler, sunucu tarafında doğrular. Keycloak'a bırakacağınız tek bir provider JAR olarak sunulur.

Kapsadıkları

Aşağıdaki her akış, ayrı bir kimlik doğrulama adımı olarak eklenir — yalnızca korumak istediğiniz ekranları korursunuz.

• Tarayıcı girişi (kullanıcı adı / parola formu)
• Kendi kendine kayıt
• Parola sıfırlama ("parolamı unuttum" ekranı)

Doğrulama, varsayılan olarak kayan bir widget (float) ya da tıkla-aç modal (popup) şeklinde görüntülenir.

Kurulum

1. JAR dosyasını edinin

Eklenti şu adreste açık kaynak olarak mevcuttur: github.com/Captcha-La/captchala-keycloak. İki seçenek:

• Sürümü indirin (önerilir) — deponun Releases sayfasından keycloak-captchala-<version>.jar dosyasını alın.
• Kaynaktan derleyin — depoyu git clone ile klonlayın ve mvn clean package komutunu çalıştırın; JAR dosyası target/ klasöründe oluşturulur.

Eklenti, Keycloak ≥ 26 (Quarkus) ve Java 17 hedefler.

2. Dağıtın

cp keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build
# Keycloak'ı yeniden başlatın

Ardından giriş temasını ayarlayın: Realm settings → Themes → Login theme → captchala.

3. Anahtarlarınızı alın

dash.captcha.la üzerinden kaydolun, bir uygulama oluşturun ve şunları kopyalayın:

• App Key — genel, sayfaya gömülür
• App Secret — yalnızca sunucu tarafı, Keycloak tarafından tek kullanımlık token oluşturmak ve /v1/validate çağırmak için kullanılır

4. Akışları bağlayın

Yönetici konsolunda, korumak istediğiniz her akışa eşleşen yürütmeyi ekleyin, ardından App Key ve App Secret anahtarlarınızı yapıştırmak için dişli simgesine tıklayın:

• Tarayıcı girişi — browser akışını kopyalayın, Username Password Form yerine Captchala Username Password Form (REQUIRED) koyun, realm browser akışı olarak bağlayın.
• Kayıt — registration akışını kopyalayın, kayıt formu alt akışına Captchala Registration (REQUIRED) ekleyin, realm registration akışı olarak bağlayın.
• Parola sıfırlama — reset credentials akışını kopyalayın, Choose User yerine Captchala Reset Credential (choose user) (REQUIRED) koyun, realm reset-credentials akışı olarak bağlayın.

Doğrulamanın görüntülendiğini onaylamak için korunan ekranlardan birini gizli pencerede açın.

Yapılandırma

Her yürütme, kendi dişli simgesinden bağımsız olarak yapılandırılır. Anahtarlar ayarlandıktan sonra varsayılanlar hemen çalışır.

Ayar	Anahtar	Varsayılan	Açıklama
App Key	app.key	—	CaptchaLa panosundan alınan public anahtar. Zorunlu.
App Secret	app.secret	—	Sunucu gizli anahtarı. Zorunlu. Maskelenmiş saklanır, tarayıcıya asla açılmaz.
API temel URL'i	api.base	https://apiv1.captcha.la	CaptchaLa API tabanı.
Widget script URL'i	script.url	https://api.captcha.la/sdk/jslib/captchala.js	Widget JS'nin yüklendiği adres.
Widget CSS URL'i	css.url	https://api.captcha.la/sdk/jslib/captchala.css	Widget CSS'nin yüklendiği adres.
Görüntüleme modu	product	float	float (kayan widget) veya popup (modal).
Eylem etiketi	action	akış başına	Doğrulamada gönderilen action (login, register, reset).
Dil	language	realm locale	Widget dili; boş bırakılırsa Keycloak locale'ini takip eder.
Kapalı başarısız	fail.closed	true	CaptchaLa API'sine erişilemediğinde gönderimi reddeder. Açık başarısız için kapatın.
Sunucu token kullan	use.server.token	true	Daha güçlü yeniden oynatma koruması için görüntülemede tek kullanımlık sunucu token'ı oluşturur.

SSS

Eklenti ücretsiz mi?

Evet. Keycloak eklentisi ücretsiz ve açık kaynaktır. CaptchaLa ücretsiz planı ayda 10.000 doğrulamayı kapsar — ücretli planlar yalnızca daha fazla hacme ihtiyacınız varsa geçerlidir.

Hangi Keycloak sürümleri destekleniyor?

Quarkus dağıtımında Keycloak 26+, Java 17 ile 26.5.6 sürümüne göre derlendi. JAR'ı providers/ klasörüne bırakın, kc.sh build komutunu çalıştırın ve yeniden başlatın.

Hangi ekranları koruyabilir?

Tarayıcı girişi, kendi kendine kayıt ve parola sıfırlama. Her biri akışına bağımsız olarak eklenir, dolayısıyla birini, ikisini veya üçünü de koruyabilirsiniz.

App Secret tarayıcıya hiç açılıyor mu?

Hayır. Gizli anahtar maskelenmiş olarak saklanır ve yalnızca Keycloak'tan CaptchaLa API'sine X-App-Secret başlığında gönderilir. Herhangi bir sayfada, şablonda veya günlükte hiç görünmez. Her doğrulama tek kullanımlık bir token ile doğrulanır, dolayısıyla çözülen bir token yeniden kullanılamaz.

CaptchaLa API'sine erişilemezse ne olur?

Varsayılan olarak eklenti kapalı başarısız olur (gönderim reddedilir). Açık başarısız yapmak için herhangi bir yürütmede fail.closed seçeneğini kapatın — aşamalı dağıtım için kullanışlıdır, üretim için önerilmez.

Kaynak

• Eklenti deposu: github.com/Captcha-La/captchala-keycloak
• Sürümler (JAR): github.com/Captcha-La/captchala-keycloak/releases
• Sorunlar / özellik talepleri: yukarıdaki depoya kaydedilir
• İlgili: Web SDK · API Referansı