---
title: Keycloak
---

# 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**](https://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

```bash
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`](https://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`](https://github.com/Captcha-La/captchala-keycloak)
- Releases (JAR): [`github.com/Captcha-La/captchala-keycloak/releases`](https://github.com/Captcha-La/captchala-keycloak/releases)
- Issues / Feature-Wünsche: gegen das obige Repository einreichen
- Verwandt: [Web-SDK](/de/web-sdk) · [API-Referenz](/de/api-reference)