• Welcome to Azion Docs
• Guides
• How to install the hCaptcha solution through Azion Marketplace

How to install the hCaptcha solution through Azion Marketplace

Overview

hCaptcha is a serverless solution available at Azion Marketplace. This type of solution is mainly used for protecting domains against bots. It allows you to monitor traffic on your website by using the hCaptcha dashboard.

hCaptcha is a CAPTCHA (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.

It also allows website owners to earn money by displaying hCaptchas to their users.

1. Getting the solution
2. Getting the keys on hCaptcha site
3. Using the solution
   3.1 Setting up the Edge Firewall rule
   3.2 Setting up the solution
4. Setting up the Edge Firewall Rules Engine

1. Getting the solution

To use the hCaptcha solution provided by Azion’s Marketplace, you have to:

1. Log in to Real-Time Manager (RTM).
   • If you don’t have one yet, create an account by visiting the sign-up page.
2. On the upper-left corner of the page, select Products menu > Marketplace.
3. Select the search box and type “hcaptcha” or browse through the cards to find the hCaptcha solution.
4. Once you’ve found the hCaptcha card, select it to go to the solution page.
5. On the solution page, look for the Subscribe for section on the bottom-right corner.
6. Click the Get It Now button.

You’ll see a message indicating that your solution was successfully installed and is ready to use.

2. Getting the keys on hCaptcha site

To use the hCaptcha solution, you have to provide two keys: your private 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 solution 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 here: Always Challenge (free), Passive (paid), and 99.9% Passive (paid). The difference between the three models is the heuristics applied on each access. For the passive mode, there’s no challenge and the CAPTCHA will be triggered according to the behavior of the user. On the 99.9% passive, the challenge will only appear for users at high risk of being bots. Ultimately, for the free model, with the always challenge being the only method available, every request will load a challenge.
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 you have your site configured to use the hCaptcha solution. To configure our Azion’s solution, you now have to get the site-key from hCaptcha.

Still in the hCaptcha site, follow the steps:

1. In your dashboard, on the upper-menu click on Sites.
2. After loading the screen with your sites, choose the one you configured above.
3. Click the Settings button (with the gear symbol).
4. You’ll see a textfield with a string chain that’ll look like this:
   • efdb42c7-10ee-4969-8013-cfcb5f7ad007. This is your site key.
     • You can click on the Try Out button to see if everything’s working.
5. Save the site-key and the secret key to configure the Azion’s solution.

3. Using the solution

3.1 Setting up the Edge Firewall rule

To instantiate the hCaptcha solution, 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 new rule.
4. Select the domains you want to protect with the function.
5. Click the Function switch to enable functions on your edge application.
6. Click the Save button.

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

3.2 Setting up the solution

To instantiate the hCaptcha solution, 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.

In the Args JSON file you’ll pass the two keys you get on the hCaptcha site:

{
	"site_key": "efdb42c7-10ee-4969-8013-cfcb5f7ad007",
	"secret_key": "0x11c8eB6e78Bd45f058876aF59ac2fB782nbdswqu",
	"expiration_in_seconds": 86400,
	"domain": "xxxxxxxx.map.azionedge.net/",
	"after_check_redirect_url": "xxxxxxx.map.azionedge.net/",
	"cookie_secret": "KEY_16_CHAR_LONG"
}

Where:

• site_key: the site key you obtained at the hCaptcha page.
• secret_key: the secret key you obtained at the hCaptcha page.
• expiration_in_seconds: the time in seconds until the hCaptcha expires.
• domain: your domain.
• after_check_redirect_url: the URL you want to redirect after the user passes the hCaptcha test.
• cookie_secret: this cookie is generated by the function and used in order for the functions not to be re-run.

Due to the algorithm used in cryptography, the cookie_secret key must have 16 or 32 characters.

Click the Save button to save your configuration.

Done. Now your hCaptcha instance is saved.

Optionally, you can pass other parameters to customize the messages you want on your hCaptcha and a custom HTML to render the challenge.

{
    "custom_message": "My message",
    "custom_html": "<html>... <!-- azion_captcha -->  .. </html>",
    "captcha_args": {
        "theme": "dark",
        "size": "compact"
    }
}

Where:

• custom_message: it’s a customized message you want to show to the users.
• custom_html: it’s the customized HTML to render the hCaptcha challenge box.
• captcha_args: you can use this to modify the layout of the challenge box to a different one from the default.

4. Setting up the Edge Firewall Rules Engine

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 solution 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 hCaptcha function according to the name you gave it in the instantiate step.
5. Click the Save button.

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

Didn’t find what you were looking for? Open a support ticket.