# Enabling reCAPTCHA

To safeguard registration against bots, Keycloak has integration with Google reCAPTCHA (see [Setting up Google reCAPTCHA](#procedure_recaptcha)) and reCAPTCHA Enterprise (see [Setting up Google reCAPTCHA Enterprise](#procedure_recaptcha_enterprise)). The default theme (`register.ftl`) supports both v2 (visible, checkbox-based) and v3 (score-based, invisible) reCAPTCHA (see [Choose the appropriate reCAPTCHA key type](https://docs.cloud.google.com/recaptcha/docs/choose-key-type)).

## Setting up Google reCAPTCHA

1. Enter the following URL in a browser:

   ```bash
   https://www.google.com/recaptcha/admin/create
   ```

2. Create a reCAPTCHA and choose between Challenge v2 (visible checkbox) or Score-based, v3 (invisible) to get your reCAPTCHA site key and secret. Note them down for future use in this procedure.

   > **NOTE:** localhost domains are not supported by default. If you wish to continue supporting them for development you can add them to the list of supported domains for your site key.

3. Navigate to the Keycloak admin console.

4. Click **Authentication** in the menu.

5. Click the **Flows** tab.

6. Select **Registration** from the list.

7. Set the **reCAPTCHA** requirement to **Required**. This enables reCAPTCHA.

8. Click the **gear icon** ⚙️ on the **reCAPTCHA** row.

   reCAPTCHA config

   ![recaptcha config](../images/recaptcha-config.png)
   1. Enter the **reCAPTCHA Site Key** generated from the Google reCAPTCHA website.

   2. Enter the **reCAPTCHA Secret** generated from the Google reCAPTCHA website.

   3. Toggle **reCAPTCHA v3** according to your Site Key type: on for score-based reCAPTCHA (v3), off for challenge reCAPTCHA (v2).

   4. (Optional) Toggle **Use recaptcha.net** to use `www.recaptcha.net` instead of `www.google.com` domain for cookies. See [reCAPTCHA faq](https://developers.google.com/recaptcha/docs/faq) for more information.

9. Authorize Google to use the registration page as an iframe.

   > **NOTE:** In Keycloak, websites cannot include a login page dialog in an iframe. This restriction is to prevent clickjacking attacks. You need to change the default HTTP response headers that is set in Keycloak.

1. Click **Realm Settings** in the menu.

   2. Click the **Security Defenses** tab.

   3. Enter <https://www.google.com> in the field for the **X-Frame-Options** header (or `https//www.recaptcha.net` if you enabled **Use recaptcha.net**).

   4. Enter <https://www.google.com> in the field for the **Content-Security-Policy** header (or `https//www.recaptcha.net` if you enabled **Use recaptcha.net**).

## Setting up Google reCAPTCHA Enterprise

1. Enter the following URL in a browser:

   ```bash
   https://developers.google.com/recaptcha/
   ```

2. Create a key for a "Website" platform, and choose the desired key type. Leave the defaults for v3 reCAPTCHA (invisible), or toggle **Use checkbox challenge** for a v2 reCAPTCHA (visible). Note the site key for future use in this procedure.

   > **NOTE:** The localhost works by default. You do not have to specify a domain.

3. On your Google Cloud Project, go to **Credentials** and create an API key.

   > **NOTE:**
> **edit api key** **reCAPTCHA Enterprise API**

4. Navigate to the Keycloak Admin Console.

5. Click **Authentication** in the menu.

6. Click the **Flows** tab.

7. Duplicate the "registration" flow.

8. Bind the new flow to the **Registration flow**.

9. Edit the new flow:

   1. Delete the **reCAPTCHA** step.

   2. Add the step **reCAPTCHA Enterprise** as a sub-step of "registration form" (first step of the flow).

10. Set the **reCAPTCHA Enterprise** requirement to **Required**.

11. Click the **gear icon** ⚙️ on the **reCAPTCHA Enterprise** row.

    reCAPTCHA Enterprise config

    ![recaptcha enterprise config](../images/recaptcha-enterprise-config.png)
    1. Enter the **Recaptcha Project ID** of your Google Cloud console project.

    2. Enter the **Recaptcha Site Key** generated at the beginning of the procedure.

    3. Enter the **Recaptcha API Key** generated at the beginning of the procedure.

    4. Toggle **reCAPTCHA v3** according to your Site Key type: on for score-based reCAPTCHA (v3), off for challenge reCAPTCHA (v2).

    5. (Optional) Customize the **Min. Score Threshold** as you see fit. Set it to the minimum score, between 0.0 and 1.0, that a user should achieve on reCAPTCHA to be allowed to register. See [interpret scores](https://docs.cloud.google.com/recaptcha/docs/interpret-assessment-website#interpret_scores).

    6. (Optional) Toggle **Use recaptcha.net** to use `www.recaptcha.net` instead of `www.google.com` domain for cookies. See [reCAPTCHA faq](https://developers.google.com/recaptcha/docs/faq) for more information.

12. Authorize Google to use the registration page as an iframe. See the last steps of [Setting up Google reCAPTCHA](#procedure_recaptcha) for a detailed procedure.

Additional resources

* For more information on extending and creating themes, see the [Server Developer Guide](https://www.keycloak.org/docs/DEV/server_development/).