# How to Install the reCAPTCHA Integration

**reCAPTCHA** is a *serverless* integration available at Azion Marketplace. This type of integration is mainly used for protecting domains against bots. It allows you to monitor traffic in your website by using the Google Dashboard for reCAPTCHA.

reCAPTCHA is a CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) integration designed to protect websites from bots and automated scripts by using a challenge-response test to determine whether the user is a human or a machine.

Google maintains and owns reCAPTCHA and uses the data collected by reCAPTCHA to improve their services.

---

## Getting the integration

To install the reCAPTCHA integration provided by Azion Marketplace, you have to:

1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Marketplace**.
2. On the Marketplace homepage, select the integration's card.
3. Once the integration's page opens, click the **Install** button.

You'll see a message indicating that your integration was successfully installed.

:::tip
You can search any integration by browsing through the cards, using the filters, or typing a keyword in the search bar.
:::

---

## Getting the keys on Google's reCAPTCHA site

To use the Azion **reCAPTCHA** integration, you have to provide two keys: your `secret-key` and your `site-key`. To get these credentials, you'll have to register at Google. 

To do so, follow these steps:

1. Go to [Google reCAPTCHA admin dashboard](https://developers.google.com/recaptcha).
 - If you don't have a Google Account, you'll be prompted to create one.
2. Once you've signed-up to the reCAPTCHA account, you'll be redirected to the website's register page.
3. On this page, you have to fill in:
    - A label for your new reCAPTCHA site.
    - The version of reCAPTCHA you want to use (you can choose from v2 or v3).
        - If you choose v2, you'll be prompted to choose what kind of test you want to apply on your website. The options are: "*I'm not a robot checkbox*", "*Invisible reCaptcha*", and "*reCaptcha Android*".
        - **Important**: Azion reCAPTCHA integration was conceived to work with the v2 invisible option.
    - The domain you want to run the reCAPTCHA. Remember to ignore the `http://` or `https://` for the domain name. If you're testing through an Azion hostname, add it here as well (see [Troubleshooting](#recaptcha-not-working-on-azion-domain)).
    - You have to accept the reCAPTCHA terms of service.
    - You have to choose if you want to receive alerts from Google about your site, such as misconfigurations and others.
4. Once you fill in all the information, click the **Submit** button.

Now you have your site registered to use the reCAPTCHA. In the next screen, you'll receive your keys: `Site Key` and `Secret Key`.

These two keys will be used to configure the Azion reCAPTCHA integration later on.

---

## Configuring the integration

### Setting up a firewall

To start the configuration of the **reCAPTCHA** integration, follow these steps:

1. On the **Products menu**, select **Firewall** in the **SECURE** section.
2. Click the **+ Firewall** button.
3. Give an easy-to-remember name to your firewall.
4. Click the **Functions** switch to enable functions.
5. Click the **Save** button.

Done. Now you have instantiated the rule for your function.

### Setting up the Firewall function

To instantiate the reCAPTCHA integration, while still on the **Firewall** page:

1. Select the **Functions Instances** tab.
2. Click the **+ Function Instance** button.
3. Give an easy-to-remember name to your instance.
4. On the dropdown menu, select the **reCAPTCHA** function.
 - This action will load the **Arguments** tab.
5. In the **Arguments** tab, you'll pass the two keys you get on the reCAPTCHA site and your variables:

```json
{
  "site_key": "efdb42c7-10ee-4969-8013-cfcb5f7ad007",
  "secret_key": "0x11c8eB6e78Bd45f058876aF59ac2fB782nbdswqu",
  "cookie_secret": "A key to sign the cookies",
  "expiration_in_seconds": 3600,
  "origin_address": "https://xxxxxxxx.map.azionedge.net",
  "origin_headers": {
	"X-Custom": "value",
	"X-Another-Custom": "another-value"
  },
  "captcha_args": {
	"theme": "dark",
	"size": "compact",
"custom_message": "My message",
     "custom_html": "<html>... <!-- azion_captcha -->  .. </html>"
  }
}
```

Where:

| Variable | Required | Description |
| ---- | ----- | ----- |
| `site_key` | Yes | The site key you obtained at the reCAPTCHA page |
| `secret_key` | Yes | The secret key you obtained at the reCAPTCHA page |
| `expiration_in_seconds` | Yes | The time *in seconds* until the reCAPTCHA expires |
| `origin_address` | Yes | Your domain from which the function will fetch the content after the user solves the CAPTCHA challenge |
| `origin_headers` | No | Whenever the access to the origin requires the usage of specific request headers |
| `captcha_args` | No | These args modify and customize the layout of the challenge box |
| `custom_message` | No | A customized message you want to show to the users |
| `custom_html` | No | The customized HTML to render the reCAPTCHA challenge box |
| `cookie_secret` | Yes | This cookie is generated by the function and used in order for the functions not to be re-run |

:::note
Due to the algorithm used in cryptography, any string of any length can be used as `cookie_secret`. 
:::

6. Click the **Save** button to save your configuration.

Done. Now your reCAPTCHA instance is saved.

### Setting up the Firewall Rules Engine

To finish, you have to set up the **Rules Engine** to configure the *behavior* and the *criteria* to run the function.

Still on the **Firewall** page:

1. Select the **Rules Engine** tab.
2. Click the **+ Rule Engine** button.
3. Give a name to the rule.
4. Select a *criteria* to run and catch the domains that you want to run the integration on.
  - Example: if `Host` *matches* `yourdomain.com`.
5. Below, select a *behavior* to the *criteria*. In this case, it'll be **Run Function**. 
    - Select the adequate function according to the name you gave it during the instantiation step.
6. Click the **Save** button.

On the Console, you must now configure your domain so your firewall protects it.

7. On the **Products menu**, select **Workloads**.
8. Click on the domain you want to protect with your reCAPTCHA function.
9. In the **Settings** section, click on the `Firewall` selector and choose the firewall you created.
10. Click the **Save** button.

Done. Now the **reCAPTCHA** integration is running for every request made to the domain you indicated.

:::warning
Since requests to your application are processed through Azion's infrastructure, Google's reCAPTCHA service validates the domain from which the challenge is served — which will be your Azion domain (for example, `yourdomain.map.azionedge.net` or your custom domain). If this domain isn't registered in your Google reCAPTCHA settings, the challenge will fail.
To fix this, go back to the [Google reCAPTCHA admin dashboard](https://www.google.com/recaptcha/admin), select your site, and add your Azion domain to the **Domains** list. This ensures Google accepts reCAPTCHA validations originating from your Azion-powered application.
:::

Watch a video about how to install the reCAPTCHA integration through Azion Marketplace on Azion’s YouTube channel:

<Video src="https://www.youtube.com/embed/X-S1qDdVVbg?si=J7dzeymFxJH0P_Zs" title="How to Install the reCAPTCHA Integration" description="reCAPTCHA is an integration to block attacks from bots, SPAM and others." uploadDate="2023-09-28" />

---

## Troubleshooting

### reCAPTCHA not working on Azion domain

**Symptom**: reCAPTCHA fails to load or returns an error when accessing your application through an Azion hostname (for example, `xxxx.map.azionedge.net`).

**Cause**: Google reCAPTCHA validates requests against a list of authorized domains. If the Azion hostname isn't registered in your reCAPTCHA settings, Google will reject the challenge, causing the integration to fail.

**Solution**: Add your Azion domain to the list of authorized domains in the Google reCAPTCHA admin console.

1. Go to the [Google reCAPTCHA admin console](https://www.google.com/recaptcha/admin).
2. Select the site you registered for this integration.
3. Under **Domains**, click **Add a domain**.
4. Enter your Azion hostname. For example: `xxxx.map.azionedge.net`.
   - If you're using a custom domain, add that domain as well.
5. Click **Save**.

After saving, reCAPTCHA will recognize requests coming from the Azion hostname and the integration will work as expected.

:::tip
During development and testing, add your Azion internal hostname (`*.map.azionedge.net`) to the authorized domains list. Once you point your custom domain to Azion, add that domain too and remove the internal hostname if it's no longer needed.
:::

---