CaptchaFox for Keycloak


  1. Download the newest release (opens in a new tab) from the GitHub Repository.
  2. Copy the downloaded keycloak-captchafox.jar into the providers directory of your keycloak installation.


To enable the installed provider, follow the next steps.

Keycloak Admin Console

Inside your Realm, click on Authentication in the left menu and go to the Flows tab.

Step 1

Here, duplicate the Registration flow, give it a name and open it.

Step 2

Step 3

Next, remove the Recaptcha step from the form.

Step 4

Now, add the CaptchaFox execution step to the Registration Form.

Step 5 Step 6

In the dropdown next to the name, set the requirement to Required to show CaptchaFox on the form later.

Step 7

Next, click on the cog icon to open the step settings. There, set an alias and enter your Site Key and Secret Key from your CaptchaFox Admin Portal.

Step 8

The final step in the Keycloak Admin Console is to bind the registration flow to the newly created one.

Step 9

Step 10

Update the template

To show the CaptchaFox widget on your form HTML, you need to also modify the registration template. You can find the files in your Keycloak installation under themes/base/login/ or your custom theme. If you use the user profile preview (-Dkeycloak.profile=preview), you need to edit the register-user-profile.ftl, else the register.ftl.

Inside the file, replace the recaptcha code block with the following:

<#if captchaFoxRequired??>
    <div class="form-group">
        <div class="${properties.kcInputWrapperClass!}">
            <div class="captchafox" data-mode="${captchaFoxMode!'inline'}" data-sitekey="${captchaFoxSiteKey}"></div>

Step 11

Final result

This is an example on how it looks like after the configuration is complete:


(Optional) Update the messages

The plugin currently uses the same messages as the recaptcha implementation. You can change them by opening the respective message file (e.g. theme/base/login/messages/ and updating the keys.

recaptchaFailed=Invalid Captcha
recaptchaNotConfigured=Captcha is required, but not configured