Keycloak CAPTCHA Plugin

The following tutorial will guide you on how to integrate the TrustCaptcha CAPTCHA solution into your Keycloak website to protect it from bots and spam.

You should have already completed the following steps before you start to integrate TrustCaptcha into your Keycloak website.

1. Read Get-Started: Get a quick overview of the concepts behind TrustCaptcha and the integration process in get started.

2. Existing CAPTCHA: If you don’t have a CAPTCHA yet, sign in or create a new user account. Then create a new CAPTCHA.

3. Existing Keycloak website: You need a Keycloak website in which you want to integrate TrustCaptcha.

Keycloak uses flows that you can edit and customize. Our Keycloak CAPTCHA extension for TrustCaptcha currently supports the following Keycloak flows:

• Registration
• Login
• Forgot Password

Install our TrustCaptcha plugin into your Keycloak installation as follows:

1. Download the latest version of our plugin trustcaptcha_keycloak_2-0-0.jar here.
2. Copy the file trustcaptcha_keycloak_2-0-0.jar to the providers directory of your Keycloak installation.

The following guides (and practical video examples) show you how to integrate TrustCaptcha into various Keycloak flows.

Steps to integrate TrustCaptcha into your registration flow:

1. Log in as an admin to your Keycloak installation.
2. In your realm, navigate to Authentication → Flows.
3. Duplicate the existing registration flow, give it a new name (e.g., Registration (TrustCaptcha)) and confirm the duplication.
4. Click on the top step, then click Add → Add step. Search for TrustCaptcha / Registration Form Action and add this step.
5. Position the new TrustCaptcha step at the same level above or below the existing Recaptcha step and then delete the Recaptcha step.
6. Open the Settings of the new TrustCaptcha step, set the Alias (e.g., tc-registration), enter your CAPTCHA’s site-key and secret-key, and save the settings. You can find these keys in your CAPTCHA settings.
7. Finally, click on Actions → Bind flow. Select the flow type Registration flow and click Save.
8. TrustCaptcha is now ready for use in the registration form! 🎉

The video visually demonstrates the most important steps.

Steps to integrate TrustCaptcha into your login flow:

1. Log in as an admin to your Keycloak installation.
2. In your realm, navigate to Authentication → Flows.
3. Duplicate the existing browser flow, give it a new name (e.g., Browser (TrustCaptcha)) and confirm the duplication.
4. Click on Add step. Search for TrustCaptcha / Username Password Form and add this step.
5. Position the new TrustCaptcha step at the same level above or below the existing Username Password Form step and then delete the Username Password Form step.
6. Open the Settings of the new TrustCaptcha step, set the Alias (e.g., tc-login), enter your CAPTCHA’s site-key and secret-key, and save the settings. You can find these keys in your CAPTCHA settings.
7. Finally, click on Actions → Bind flow. Select the flow type Browser flow and click Save.
8. TrustCaptcha is now ready for use in the login form! 🎉

The video visually demonstrates the most important steps.

Steps to integrate TrustCaptcha into your forgot password flow:

1. Log in as an admin to your Keycloak installation.
2. In your realm, navigate to Authentication → Flows.
3. Duplicate the existing reset credentials flow, give it a new name (e.g., Reset Credentials (TrustCaptcha)) and confirm the duplication.
4. Click on Add step. Search for TrustCaptcha / Reset Credentials Choose User and add this step.
5. Position the new TrustCaptcha step at the same level above or below the existing Choose User step and then delete the Choose User step.
6. Open the Settings of the new TrustCaptcha step, set the Alias (e.g., tc-reset), enter your CAPTCHA’s site-key and secret-key, and save the settings. You can find these keys in your CAPTCHA settings.
7. Finally, click on Actions → Bind flow. Select the flow type Reset credentials flow and click Save.
8. TrustCaptcha is now ready for use in the forgot password form! 🎉

The video visually demonstrates the most important steps.

TrustCaptcha offers two options for frontend integration:

With this option, TrustCaptcha automatically integrates into the existing login, registration, and forgot password forms of Keycloak. TrustCaptcha looks for button or input elements with type="submit" and integrates itself above them.

If you don’t use button/input elements with type="submit", or you want to customize the CAPTCHA for design reasons, you can disable the Insert Automatically feature in the TrustCaptcha settings. You can then define a div container with the class trustcaptcha in your templates. TrustCaptcha will automatically integrate above this container.

Custom Template

<!-- your input fields -->

<div class="trustcaptcha"></div>

<!-- further input fields / submit button -->

Once you have successfully installed and configured TrustCaptcha on your website, you can use TrustCaptcha to its full extent. However, we still recommend the following additional technical and organizational measures:

• Security rules: You can find many security settings for your CAPTCHA in the CAPTCHA settings. These include, for example, authorized websites, CAPTCHA bypass for specific IP addresses, bypass keys, IP based blocking, geoblocking, individual difficulty and duration of the CAPTCHA, and much more. Learn more about the security rules.

• Data protection: Include a passage in your privacy policy that refers to the use of TrustCaptcha. We also recommend that you enter into a data processing agreement with us to stay GDPR-compliant. Learn more about data protection.

• Accessibility: Customize TrustCaptcha to your website so that your website is as accessible as possible and offers the best possible user experience. More about accessibility.

• Testing: If you use automated testing, make sure that the CAPTCHA does not block it. Learn more about testing.