---
name: azion-install-the-hcaptcha-integration
description: >-
  Install hCaptcha from Azion Marketplace and run its challenge on a firewall, so only requests that pass it reach your origin.
---

# Install the hCaptcha integration

You install the hCaptcha integration from Azion Marketplace and run it on a [Firewall](/en/documentation/platform/firewall/), from Azion Console. hCaptcha is a CAPTCHA service: it shows a challenge that is hard for bots, web crawlers, and other automated tools to solve, and the integration lets a request reach your origin only after the challenge is solved.

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.
- An hCaptcha account, with a site key and a 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 `hCaptcha` 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 hCaptcha keys

The integration needs two keys from hCaptcha: your secret key and your site key. You get both from the hCaptcha website. To register your site:

1. **Open the hCaptcha dashboard**

   Go to the [hCaptcha dashboard](https://dashboard.hcaptcha.com/overview). If you do not have an account, [create one](https://www.hcaptcha.com/signup-interstitial).

   When you create the account, the site gives you your secret key. You use this key to configure the integration, so store it in a safe place.

2. **Select Add Site**

3. **(Optional) Name your hCaptcha instance**

   A name is optional, but recommended.

4. **Add the hostnames**

   Enter the `hostnames` that show the challenge, then select **Add Domain**.

5. **Select the challenge mode**

   Select one of three modes:

   - **Always Challenge**: free. Every request loads a challenge.
   - **Passive**: paid. No challenge shows, and the CAPTCHA triggers from the behavior of the user.
   - **99.9% Passive**: paid. The challenge shows only to users at high risk of being bots.

6. **Select the passing threshold**

   Select the difficulty level: *auto*, *easy*, *moderate*, or *difficult*. The level sets how accurate the answers of a user must be to pass the test.

7. **Select Save**

Your site is configured to use hCaptcha. To copy the site key:

1. **Open the sites list**

   In the dashboard menu, select **Sites**.

2. **Find your site**

   Find the site you configured. The first column shows a string like `efdb42c7-10ee-4969-8013-cfcb5f7ad007`. This string is your site key.

3. **Copy the site key**

   Hover over the string and select it to copy your site key.

You have the site key and the secret key that 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: `hcaptcha-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 hCaptcha 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: `hcaptcha`.

4. **Select the installed function**

   In **Function**, select the hCaptcha 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 and your variables:

```json
{
  "site_key": "<your_site_key>", // Replace with your site key
  "secret_key": "<your_secret_key>", // Replace with your secret key
  "cookie_secret": "A key to sign the cookies",
  "expiration_in_seconds": 3600,
  "origin_address": "https://xxxxxxxx.map.azionedge.net", // Replace with your domain
  "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 hCaptcha page                                                                |
| `secret_key`            | Yes      | The secret key you got from the hCaptcha page                                                              |
| `expiration_in_seconds` | Yes      | The time, in seconds, until the challenge expires                                                          |
| `origin_address`        | Yes      | Your domain, from which the function fetches the content after the user solves the 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 challenge box                                                             |
| `cookie_secret`         | Yes      | The key that signs the cookie the function generates, so the function does not run again for the same user |

> **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 hCaptcha`.

4. **Set the criterion**

   In the **Criteria** section, select the domain that runs the integration. For example: if `Hostname` *is equal* `xxxxxxxxxxxx.map.azionedge.net`.

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 hCaptcha instance on each one.

---

## Trademarks

hCaptcha is a registered trademark of Intuition Machines, Inc.

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

[How to Install the hCaptcha® Integration](https://www.youtube.com/watch?v=HqdX9wAWJDg)

hCaptcha is an integration to protect your assets from bot attacks, SPAM, and others.

---

## 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.
- [Update an integration](/en/documentation/guides/application-development/integrations/update-an-integration.md): Move an installed integration to its latest version.