• Guides
• Hcaptcha

hCaptcha® is a CAPTCHA (which stands for “Completely Automated Public Turing test to tell Computers and Humans Apart”) service that aims to improve user privacy and security by using puzzles that are harder for bots to solve, and by using the solved puzzles to train machine learning models to improve the overall security of the internet. You can use it to avoid bots, web crawlers, and other automated tools that misuse your resources.

Azion’s integration with hCaptcha® runs on the edge nodes of Azion. It ensures that only authentic requests get access to your infrastructure by identifying whether the request is valid before accessing the origin. Rather than figuring out the logic of when, where, and how to display requests, you can speed up your requests by simply enabling and configuring JSON args.

To install this integration provided by Azion’s Marketplace, you have to:

1. Access Azion Console > Marketplace.
2. On the Marketplace homepage, select the integration’s card.
3. Once the integration’s page opens, click the Get It Now button, at the bottom-right corner of the page.

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

To configure this integration, you have to provide two keys: your secret-key and your site-key. To get these credentials, you’ll have to register at the hCaptcha site.

To do so, follow these steps:

1. Go to the hCaptcha dashboard.
   • If you don’t have an account, you can create one here.
   • Pay attention when creating a new account, because the site will provide your secret key. This secret key will be used to configure the integration later on.
2. On the dashboard click the New Site button.
3. It’s optional, but recommended, to name your instance of hCaptcha.
4. Fill in the hostnames you want to use the challenge on and click the Add Domain button.
5. Choose your challenge mode. You have three options:

• Always Challenge (Free. Every request will load a challenge)
• Passive (Paid. There’s no challenge and the CAPTCHA will be triggered according to the behavior of the user)
• 99.9% Passive (Paid. The challenge will only appear for users at high risk of being bots).

6. Choose the passing threshold you want for your site according to the difficulty level: auto, easy, moderate, and difficult. These modes will determine how accurate the user’s answers should be to pass the test.
7. With everything filled-up, click the Save button on the top-right corner.

Now your site is configured to use the hCaptcha integration.

To configure Azion’s integration, you now have to get the site-key from hCaptcha. Still in the hCaptcha site, follow these steps:

1. In your dashboard, on the upper-menu, click on Sites.
2. After loading your sites listed, find the one you configured above. In the first column, you’ll see a label with a string chain that’ll look like this: efdb42c7-10ee-4969-8013-cfcb5f7ad007. This is your site key.
3. Hover over the string and click to copy your site key.
4. Save the site key and the secret key to configure Azion’s integration as explained in the next sections.

To start the configuration, follow these steps:

1. On the Products menu, select Edge Firewall in the SECURE section.
2. Click the Add Rule Set button.
3. Give an easy-to-remember name to your edge firewall.
4. Select the domains you want to protect with the function.
5. Click the Edge Functions switch to enable functions on your edge application.
6. Click the Save button.

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

To instantiate the integration, while still on the Edge Firewall page, select the Functions tab and follow these steps:

1. Click the Add Function button.
2. Give a name to your instance.
3. On the dropdown menu, select the hCaptcha function.

• This action will load the function, showing a form with the function’s source-code and, just above it, two tabs: Code and Args. By clicking on the Code tab, you’ll be able to navigate through the source-code, but won’t be able to change it.

4. In the Args tab, you’ll pass the two keys your keys and your variables:

{
  "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:

5. Click the Save button to save your configuration.

Done. Now your hCaptcha instance is saved.

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

Still on the Edge Firewall page, select the Rules Engine tab and follow these steps:

1. Click the New Rule button.
2. Give a name to the rule.
3. Select a criteria to run and catch the domain you want to run the integration on. Example: if Hostname is equal xxxxxxxxxxxx.map.azionedge.net.
4. 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 in the instantiate step.
5. Click the Save button.

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

hCaptcha is a registered trademark of Intuition Machines, Inc.

Contributors