Captchala Keycloak Plugin

Protects Keycloak browser login, self-registration, and reset-password forms with a Captchala challenge, verified server-side.

• Keycloak: 26.5.6+ (Quarkus). Java 17.
• Render mode: floating widget (float, default) or popup.
• Server-side verification: the plugin mints a one-time server_token and validates the returned pass_token against the Captchala API.

Build

cd keycloak-plugin
mvn clean package
# -> target/keycloak-captchala-1.0.0.jar

Install

1. Copy the JAR into Keycloak:

   cp target/keycloak-captchala-1.0.0.jar /opt/keycloak/providers/
   /opt/keycloak/bin/kc.sh build

2. Restart Keycloak.
3. Select the login theme: Realm settings → Themes → Login theme → captchala.

Configure the flows

You need a Captchala App Key and App Secret (dashboard → your app).

Browser login

1. Authentication → Flows, duplicate the browser flow.
2. In the forms sub-flow, replace Username Password Form with Captchala Username Password Form (REQUIRED).
3. Click the gear icon → set App Key, App Secret, and any overrides.
4. Action → Bind flow → Browser flow.

Registration

1. Duplicate the registration flow.
2. In the registration form sub-flow, add execution Captchala Registration (REQUIRED).
3. Gear icon → set App Key / App Secret.
4. Bind as the realm Registration flow.

Reset password

1. Duplicate the reset credentials flow.
2. Replace Choose User with Captchala Reset Credential (choose user) (REQUIRED).
3. Gear icon → set App Key / App Secret.
4. Bind as the realm Reset credentials flow.

Configuration reference

Key	Default	Notes
app.key	—	Public app key
app.secret	—	Private app secret (masked)
product	float	float or popup
action	per flow	login / register / reset
language	realm locale	Widget language
fail.closed	true	Deny when the API is unreachable
use.server.token	true	Mint a one-time server token at render

How it works

1. On render, the provider mints a server_token (POST /v1/server/challenge/issue) and injects the widget config.
2. The user solves the floating widget; the SDK returns a pass_token.
3. On submit, the provider validates it (POST /v1/validate, keep_token:false); only data.valid (or data.degraded) continues the flow.