Install the hCaptcha integration
Install hCaptcha from Azion Marketplace and run its challenge on a firewall, so only requests that pass it reach your origin.
You install the hCaptcha integration from Azion Marketplace and run it on a 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.
- An application served by a workload, 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 installed and authorized, for the last section.
- Turning on a product or a module can generate usage costs. For more information, refer to Pricing.
Install the integration
The function is installed once per account. To install it:
Access Azion Console > Marketplace.
Enter hCaptcha in the Search on Marketplace field, then select the integration’s card. Browsing the cards and the categories reaches the same page.
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:
Go to the hCaptcha dashboard. If you do not have an account, create one.
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.
A name is optional, but recommended.
Enter the hostnames that show the challenge, then select Add Domain.
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.
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.
Your site is configured to use hCaptcha. To copy the site key:
In the dashboard menu, select Sites.
Find the site you configured. The first column shows a string like efdb42c7-10ee-4969-8013-cfcb5f7ad007. This string is your 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:
Access Azion Console > Firewalls, then create a firewall.
In the General section, enter a Name. For example: hcaptcha-firewall.
In the Modules section, turn on the Functions switch.
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.
Create the function instance
The instance holds your hCaptcha keys and the origin the function fetches after a solved challenge. To create it:
In Firewalls, select your firewall, then select the Functions Instances tab.
A firewall that has no instance shows the same action as Function Instance. The Create Instance drawer opens.
In Name, enter a name. For example: hcaptcha.
In Function, select the hCaptcha function. The list holds only the functions that run on a firewall.
In Arguments, the editor is prefilled with the integration’s default arguments in JSON. Enter your keys and values, as the next section describes.
The instance is listed in the Functions Instances tab.
Arguments
The instance takes the two keys and your variables:
| 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 |
Create the rule
The instance challenges nothing until a rule runs it. A Rules Engine for Firewall rule selects the requests that reach the instance, through a Run Function behavior. To create the rule:
In Firewalls, select your firewall, then select the Rules Engine tab.
In Name, enter a name. For example: Run hCaptcha.
In the Criteria section, select the domain that runs the integration. For example: if Hostname is equal xxxxxxxxxxxx.map.azionedge.net.
In the Behaviors section, select Run Function, then select the instance by the name you gave it.
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:
The command prints the id of the new deployment:
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.