Install the reCAPTCHA integration
Install reCAPTCHA from Azion Marketplace and run its challenge on a firewall, so bots and spam do not reach your origin.
You install the reCAPTCHA integration from Azion Marketplace and run it on a 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.
- An application served by a workload, 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 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 reCAPTCHA 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 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:
Go to the Google reCAPTCHA admin dashboard. 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.
Enter a label for your new reCAPTCHA site.
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.
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.
Accept the reCAPTCHA terms of service.
Choose if you want to get alerts from Google about your site, such as misconfigurations.
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:
Access Azion Console > Firewalls, then create a firewall.
In the General section, enter a Name. For example: recaptcha-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 reCAPTCHA 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: recaptcha.
In Function, select the reCAPTCHA 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 you got from Google and your variables:
| 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 |
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 reCAPTCHA.
In the Criteria section, select the domains that run the integration. For example: if Host matches yourdomain.com.
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 reCAPTCHA instance on each one.
Watch a video on how to install the reCAPTCHA integration through Azion Marketplace on Azion’s YouTube channel.
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:
Go to the Google reCAPTCHA admin console.
Select the site you registered for this integration.
Under Domains, select Add a domain.
Enter your Azion hostname. For example: xxxx.map.azionedge.net. If you use a custom domain, add that domain too.
reCAPTCHA accepts the requests that come from the Azion hostname, and the integration works.