# How to Install the hCaptcha® Integration 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. --- ## Getting the integration To install this integration provided by Azion's Marketplace, you have to: 1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Marketplace**. 2. On the Marketplace homepage, select the integration's card. 3. Once the integration's page opens, click the **Install** button, at the bottom-right corner of the page. You'll see a message indicating that your integration was successfully installed. :::tip You can search any integration by browsing through the cards, using the filters, or typing a keyword in the search bar. ::: --- ## Getting the keys 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](https://dashboard.hcaptcha.com/overview). - If you don't have an account, you [can create one here](https://www.hcaptcha.com/signup-interstitial). - 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, so store it somewhere safe. 2. On the dashboard click the **Add 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. --- ## Configuring the integration ### Setting up an firewall To start the configuration, follow these steps: 1. On the **Products menu**, select **Firewall** in the **SECURE** section. 2. Click the **+ Firewall** button. 3. Give an easy-to-remember name to your firewall. 4. Turn on the **Functions** switch. 5. Click the **Save** button. Done. Now you've instantiated the firewall for your integration and it has access to functions. ### Setting up the integration To instantiate the integration, while still on the **Firewall** page: 1. Select the **Functions Instances** tab. 2. Click the **+ Function Instance** button. 3. Give a name to your instance. 4. On the dropdown menu, select the *hCaptcha function*. - This action will load the **Arguments** tab, where you can add the parameters to execute your application. 5. In the **Arguments** tab, pass the two keys and your variables: ```json { "site_key": "", // Replace with your site key "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": "" } } ``` Where: | Variable | Required | Description | | ---- | ----- | ----- | | `site_key` | Yes | The site key you obtained at the hCaptcha page | | `secret_key` | Yes | The secret key you obtained at the hCaptcha page | | `expiration_in_seconds` | Yes | The time *in seconds* until the challenge expires | | `origin_address` | Yes | Your domain from which the function will fetch the content after the user solves the challenge | | `origin_headers` | No | Whenever the access to the origin requires the usage of specific request headers | | `captcha_args` | No | These args modify and customize the layout of the challenge box | | `custom_message` | No | A customized message you want to show users | | `custom_html` | No | The customized HTML to render the challenge box | | `cookie_secret` | Yes | This cookie is generated by the function and used in order for the functions not to be re-run | :::note Due to the algorithm used in cryptography, any string of any length can be used as `cookie_secret`. ::: 6. Click the **Save** button to save your configuration. Done. Now your hCaptcha instance is saved. ### Setting up the 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 **Firewall** page: 1. Select the **Rules Engine** tab. 2. Click the **+ Rule Engine** button. 3. Give a name to the rule. 4. 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`. 5. 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 during the instantiation step. 6. Click the **Save** button. On the Console, you must now configure your domain so your firewall protects it. 7. On the **Products menu**, select **Worloads**. 8. Click on the domain you want to protect with your hCaptcha function. 9. In the **Settings** section, click on the `Firewall` selector and choose the firewall you created. 10. Click the **Save** button. Done. Now the integration is running for every request made to the domain you indicated. --- ## 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.