Keycloak

Offizielles CaptchaLa-Plugin für Keycloak. Fügt eine CAPTCHA-Challenge zu Keycloaks integrierten Login-, Registrierungs- und Passwort-Zurücksetzen-Formularen hinzu, serverseitig verifiziert, ohne dass Code geschrieben werden muss. Wird als einzelne Provider-JAR geliefert, die Sie in Keycloak ablegen.

Was es abdeckt

Jeder der folgenden Flows ist als eigenständiger Authentifizierungsschritt eingebunden — Sie schützen ausschließlich die Formulare, die Sie schützen möchten.

• Browser-Login (das Benutzername/Passwort-Formular)
• Selbstregistrierung
• Passwort zurücksetzen (das „Passwort vergessen"-Formular)

Die Challenge wird standardmäßig als schwebendes Widget gerendert (float) oder als Click-to-open-Modal (popup).

Installation

1. JAR beziehen

Das Plugin ist Open Source unter github.com/Captcha-La/captchala-keycloak. Zwei Möglichkeiten:

• Release herunterladen (empfohlen) — keycloak-captchala-<version>.jar von der Releases-Seite des Repositories herunterladen.
• Aus Quellcode bauen — das Repo per git clone klonen und mvn clean package ausführen; die JAR wird unter target/ erzeugt.

Das Plugin richtet sich an Keycloak ≥ 26 (Quarkus) und Java 17.

2. Bereitstellen

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

Danach das Login-Theme setzen: Realm-Einstellungen → Themes → Login-Theme → captchala.

3. Schlüssel beziehen

Registrieren Sie sich unter dash.captcha.la, legen Sie eine Anwendung an und kopieren Sie:

• App Key — öffentlich, eingebettet in die Seite
• App Secret — ausschließlich serverseitig; Keycloak nutzt es, um einen Einmal-Token zu erstellen und /v1/validate aufzurufen

4. Flows verdrahten

Fügen Sie in der Admin-Konsole die passende Ausführung zu jedem Flow hinzu, den Sie schützen möchten, und klicken Sie auf das Zahnrad-Symbol, um App Key und App Secret einzufügen:

• Browser-Login — den browser-Flow duplizieren, Username Password Form durch Captchala Username Password Form (REQUIRED) ersetzen und als Realm-Browser-Flow binden.
• Registrierung — den registration-Flow duplizieren, Captchala Registration (REQUIRED) zum Registrierungsformular-Unterflow hinzufügen und als Realm-Registrierungsflow binden.
• Passwort zurücksetzen — den reset credentials-Flow duplizieren, Choose User durch Captchala Reset Credential (choose user) (REQUIRED) ersetzen und als Realm-Reset-Credentials-Flow binden.

Öffnen Sie eines der geschützten Formulare in einem privaten Fenster, um zu bestätigen, dass die Challenge gerendert wird.

Konfiguration

Jede Ausführung wird unabhängig über ihr Zahnrad-Symbol konfiguriert. Die Standardwerte funktionieren nach dem Eintragen der Schlüssel sofort.

Einstellung	Key	Standard	Beschreibung
App Key	app.key	—	Öffentlicher Schlüssel aus dem CaptchaLa-Dashboard. Erforderlich.
App Secret	app.secret	—	Server-Geheimnis. Erforderlich. Maskiert gespeichert, nie an den Browser ausgegeben.
API-Basis-URL	api.base	https://apiv1.captcha.la	CaptchaLa-API-Basis.
Widget-Skript-URL	script.url	https://api.captcha.la/sdk/jslib/captchala.js	Ladeort des Widget-JS.
Widget-CSS-URL	css.url	https://api.captcha.la/sdk/jslib/captchala.css	Ladeort des Widget-CSS.
Render-Modus	product	float	float (schwebendes Widget) oder popup (Modal).
Action-Label	action	pro Flow	Das bei der Validierung gesendete action-Label (login, register, reset).
Sprache	language	Realm-Locale	Widget-Sprache; leer folgt der Keycloak-Locale.
Fail closed	fail.closed	true	Ist die CaptchaLa-API nicht erreichbar, wird die Einreichung abgelehnt. Deaktivieren, um fail open zu verwenden.
Server-Token verwenden	use.server.token	true	Erstellt beim Rendern einen Einmal-Server-Token für stärkeren Anti-Replay-Schutz.

FAQ

Ist das Plugin kostenlos?

Ja. Das Keycloak-Plugin ist kostenlos und Open Source. Der kostenlose CaptchaLa-Tarif deckt 10.000 Verifizierungen pro Monat ab — kostenpflichtige Tarife greifen nur, wenn Sie mehr Volumen benötigen.

Welche Keycloak-Versionen werden unterstützt?

Keycloak 26+ in der Quarkus-Distribution, gebaut gegen 26.5.6 mit Java 17. Die JAR in providers/ ablegen, kc.sh build ausführen und neu starten.

Welche Formulare kann es schützen?

Browser-Login, Selbstregistrierung und Passwort zurücksetzen. Jedes wird unabhängig zu seinem Flow hinzugefügt, sodass Sie eines, zwei oder alle drei schützen können.

Wird das App Secret je an den Browser übermittelt?

Nein. Das Secret wird maskiert gespeichert und ausschließlich im X-App-Secret-Header von Keycloak an die CaptchaLa-API gesendet. Es erscheint nie in einer Seite, einem Template oder einem Log. Jede Challenge wird mit einem Einmal-Token verifiziert, sodass ein gelöster Token nicht wiederverwertbar ist.

Was passiert, wenn die CaptchaLa-API nicht erreichbar ist?

Standardmäßig schlägt das Plugin geschlossen fehl (die Einreichung wird abgelehnt). Setzen Sie fail.closed bei einer Ausführung auf aus, um stattdessen fail open zu verwenden — nützlich für gestaffeltes Rollout, nicht empfohlen für die Produktion.

Quelle

• Plugin-Repository: github.com/Captcha-La/captchala-keycloak
• Releases (JAR): github.com/Captcha-La/captchala-keycloak/releases
• Issues / Feature-Wünsche: gegen das obige Repository einreichen
• Verwandt: Web-SDK · API-Referenz