---
name: azion-install-the-recaptcha-integration
description: >-
  Install reCAPTCHA from Azion Marketplace and run its challenge on a firewall, so bots and spam do not reach your origin.
---

# Install the reCAPTCHA integration

You install the reCAPTCHA integration from Azion Marketplace and run it on a [Firewall](/en/documentation/platform/firewall/), from Azion Console. reCAPTCHA is a CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) service: a challenge-response test tells whether the user is a human or a machine, and so protects your domains from bots and automated scripts. You monitor the traffic of your website in the Google dashboard for reCAPTCHA. Google maintains and owns reCAPTCHA and uses the data reCAPTCHA collects to improve its services.

Five objects have to exist before a request is challenged: the installed function, a firewall carrying the **Functions** module, a function instance holding the arguments, a Rules Engine rule with the **Run Function** behavior, and a workload deployment bound to the firewall. Each section below creates one of them.

---

## Prerequisites

- An Azion account. To sign in, refer to [How to access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/).
- An application served by a [workload](/en/documentation/platform/workloads/), whose deployment you bind to the firewall in the last section.
- A Google account, with a reCAPTCHA site key and secret key. The next sections show how to get them.
- The [Azion CLI](/en/documentation/devtools/cli/) installed and authorized, for the last section.
- Turning on a product or a module can generate usage costs. For more information, refer to [Pricing](/en/documentation/fundamentals/pricing/).

---

## Install the integration

The function is installed once per account. To install it:

1. **Open Marketplace**

   Access [Azion Console](https://console.azion.com/) > **Marketplace**.

2. **Find the integration**

   Enter `reCAPTCHA` in the **Search on Marketplace** field, then select the integration's card. Browsing the cards and the categories reaches the same page.

3. **Select Install**

The card shows `Successfully installed!` and `Latest version installed!`, and the function appears in the **Function** list of the **Create Instance** drawer.

---

## Get the reCAPTCHA keys

The integration needs two keys from Google: your `secret-key` and your `site-key`. You get both when you register your site with Google. To register it:

1. **Open the reCAPTCHA admin dashboard**

   Go to the [Google reCAPTCHA admin dashboard](https://developers.google.com/recaptcha). If you do not have a Google account, the site prompts you to create one.

   After you sign up, the site opens the register page for your website.

2. **Enter a label**

   Enter a label for your new reCAPTCHA site.

3. **Select the reCAPTCHA version**

   Select *v2* or *v3*. If you select *v2*, select the type of test for your website: *I'm not a robot checkbox*, *Invisible reCaptcha*, or *reCaptcha Android*.

   The Azion reCAPTCHA integration is designed to work with the v2 invisible option.

4. **Add the domain**

   Enter the domain that runs reCAPTCHA, without `http://` or `https://`. If you test through an Azion hostname, add it too. For more information, refer to [reCAPTCHA fails on an Azion hostname](#recaptcha-fails-on-an-azion-hostname).

5. **Accept the terms of service**

   Accept the reCAPTCHA terms of service.

6. **Choose the alerts**

   Choose if you want to get alerts from Google about your site, such as misconfigurations.

7. **Select Submit**

Your site is registered to use reCAPTCHA. The next screen shows your keys, `Site Key` and `Secret Key`, which the function instance takes as arguments.

---

## Create the firewall

The firewall is where the function is instanced and where the rule that runs it lives. To create one:

1. **Open the Firewalls page**

   Access [Azion Console](https://console.azion.com/) > **Firewalls**, then create a firewall.

2. **Name the firewall**

   In the **General** section, enter a **Name**. For example: `recaptcha-firewall`.

3. **Turn on the Functions module**

   In the **Modules** section, turn on the **Functions** switch.

4. **Save the firewall**

The firewall shows a **Functions Instances** tab while the **Functions** module stays on. To use an existing firewall instead, turn on its **Functions** module and save it. For every setting on this form, refer to [Set a firewall's main settings](/en/documentation/guides/application-security/firewall-and-waf/firewall-configure-main-settings/).

---

## Create the function instance

The instance holds your reCAPTCHA keys and the origin the function fetches after a solved challenge. To create it:

1. **Open the Functions Instances tab**

   In **Firewalls**, select your firewall, then select the **Functions Instances** tab.

2. **Select + Function**

   A firewall that has no instance shows the same action as **Function Instance**. The **Create Instance** drawer opens.

3. **Name the instance**

   In **Name**, enter a name. For example: `recaptcha`.

4. **Select the installed function**

   In **Function**, select the reCAPTCHA function. The list holds only the functions that run on a firewall.

5. **Enter the arguments**

   In **Arguments**, the editor is prefilled with the integration's default arguments in JSON. Enter your keys and values, as the next section describes.

6. **Select Save**

The instance is listed in the **Functions Instances** tab.

### Arguments

The instance takes the two keys you got from Google 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>"
  }
}
```

| Variable                | Required | Description                                                                                          |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `site_key`              | Yes      | The site key you got from the reCAPTCHA page                                                         |
| `secret_key`            | Yes      | The secret key you got from the reCAPTCHA page                                                       |
| `expiration_in_seconds` | Yes      | The time, in seconds, until the reCAPTCHA expires                                                    |
| `origin_address`        | Yes      | Your domain, from which the function fetches the content after the user solves the CAPTCHA challenge |
| `origin_headers`        | No       | The request headers the origin requires, when access to it needs specific headers                    |
| `captcha_args`          | No       | The arguments that change the layout of the challenge box                                            |
| `custom_message`        | No       | A custom message to show to users                                                                    |
| `custom_html`           | No       | The custom HTML that renders the reCAPTCHA challenge box                                             |
| `cookie_secret`         | Yes      | The key that signs the cookie the function generates, so the function does not run again             |

> **Note**
>
> Because of the algorithm the cryptography uses, any string of any length can be the `cookie_secret`.

---

## Create the rule

The instance challenges nothing until a rule runs it. A [Rules Engine for Firewall](/en/documentation/platform/firewall/rules-engine/) rule selects the requests that reach the instance, through a **Run Function** behavior. To create the rule:

1. **Open the Rules Engine tab**

   In **Firewalls**, select your firewall, then select the **Rules Engine** tab.

2. **Select + Rule**

3. **Name the rule**

   In **Name**, enter a name. For example: `Run reCAPTCHA`.

4. **Set the criterion**

   In the **Criteria** section, select the domains that run the integration. For example: if `Host` *matches* `yourdomain.com`.

5. **Add the Run Function behavior**

   In the **Behaviors** section, select **Run Function**, then select the instance by the name you gave it.

6. **Select Save**

The firewall runs the instance on every request to the domain in the criterion.

---

## Bind the firewall to the workload

The binding is on the workload's deployment, so create a deployment that names both the application and the firewall:

```bash
azion create workload-deployment --workload-id <workload-id> --name <deployment-name> \
  --application-id <application-id> --firewall-id <firewall-id> --strategy-type default \
  --active true --current true
```

The command prints the id of the new deployment:

```text
Created Workload Deployment with ID 123456
```

Requests to the workload's domain reach the firewall, and the rule runs the reCAPTCHA instance on each one.

> **Caution**
>
> Requests to your application go through Azion's infrastructure, so Google's reCAPTCHA service validates the domain that serves the challenge: your Azion domain, such as `yourdomain.map.azionedge.net`, or your custom domain. If this domain is not registered in your Google reCAPTCHA settings, the challenge fails. To fix it, go to the [Google reCAPTCHA admin dashboard](https://www.google.com/recaptcha/admin), select your site, and add your Azion domain to the **Domains** list. Google then accepts the reCAPTCHA validations that come from your application on Azion.

Watch a video on how to install the reCAPTCHA integration through Azion Marketplace on Azion's YouTube channel.

[How to Install the reCAPTCHA Integration](https://www.youtube.com/watch?v=X-S1qDdVVbg)

reCAPTCHA is an integration to block attacks from bots, SPAM and others.

---

## Troubleshooting

### reCAPTCHA fails on an Azion hostname

reCAPTCHA does not load, or returns an error, when you access your application through an Azion hostname, such as `xxxx.map.azionedge.net`.

Google reCAPTCHA validates requests against a list of authorized domains. If the Azion hostname is not in your reCAPTCHA settings, Google rejects the challenge and the integration fails. To add the hostname to the authorized domains:

1. **Open the reCAPTCHA admin console**

   Go to the [Google reCAPTCHA admin console](https://www.google.com/recaptcha/admin).

2. **Select your site**

   Select the site you registered for this integration.

3. **Select Add a domain**

   Under **Domains**, select **Add a domain**.

4. **Enter the Azion hostname**

   Enter your Azion hostname. For example: `xxxx.map.azionedge.net`. If you use a custom domain, add that domain too.

5. **Select Save**

reCAPTCHA accepts the requests that come from the Azion hostname, and the integration works.

> **Tip**
>
> During development and tests, add your Azion internal hostname (`*.map.azionedge.net`) to the authorized domains list. After you point your custom domain to Azion, add that domain too, and remove the internal hostname if you no longer need it.

---

## Next steps

- [Marketplace integrations](/en/documentation/platform/marketplace/integrations.md): Every integration Azion Marketplace offers, and where each one runs.
- [Rules Engine for Firewall](/en/documentation/platform/firewall/rules-engine.md): Every criterion and behavior a firewall rule accepts.
- [Install the hCaptcha integration](/en/documentation/guides/application-development/integrations/hcaptcha.md): Run the hCaptcha challenge on a firewall instead.
- [Update an integration](/en/documentation/guides/application-development/integrations/update-an-integration.md): Move an installed integration to its latest version.