Cloudflare Worker Deployment Guide

Overview

For clients using Cloudflare it is possible to deploy the BotGuard for Applications solution without performing any modification to your front-end and back-end code.

We leverage Cloudflare’s Worker technology to integrate with the solution.

Upon requests to specific routes (as configured) the following happens: * The Detection Tag is injected into the HTML of the page(s); * When a protected event submission happens, a request is sent to the BotGuard for Applications API synchronously. The response is added to the headers of the request that is forwarded to your web server.

Note: Routes can be specified as Regex strings to make the Worker run on multiple routes with a common prefix.

Multiple routes can be configured per Worker. However, a single route cannot have multiple Workers active.

Requirements

  1. Cloudflare account.
  2. Configure your domain’s nameserver (NS) record to the appropriate Cloudflare nameserver as specified in the Cloudflare Guide.
  3. Conduct a call to our system to provide information related to the form submissions that you wish to protect in order for our team to customize the Cloudflare Worker code for maximized detection efficacy.

Content Retrieval

  1. [Only for mode: 2 (Active)] Your API Key for Cloudflare can be retrieved here.
  2. One of our team members will share your customized Worker Code(s) with you by email.

Deployment

There are three steps to successfully configuring the Cloudflare Worker integration:

  1. Add a Cloudflare Worker
  2. Configure the Worker
  3. Configure the routes

1. Add a Cloudflare Worker

First, you will need to add a Cloudflare Worker, which is a script that will run on every request/response made toward the client’s server (for a route to be specified later).

  1. Login into your Cloudflare account.
  2. On the “Home” page, select the website that you wish to protect.
  3. Then, click on the “Workers” button. Create a Worker
  4. On the Workers page, click on “Manage Workers.” Manage workers
  5. Then, click on “Create a Worker.” Create a Worker
  6. A screen divided into different parts will appear. Change the name of the file so that it is easily recognizable and accessible. (Example: “human-security-contactform” instead of human-frog-9e98”.) Change Name of File
  7. Paste the code provided to you by your representative on the left-hand side of the screen (where templated code is). Create a Worker

Now you have a templated version of the code in the Worker. The next step is to configure the Worker with your unique client data.

Note: repeat the steps in this section for every Worker code you received from our team.

2. Configure the Worker [only for mode: 2 (Active)]

The only information remaining to be added to the Worker is the API key, shared with you separately. This is only necessary if the integration is implemented with mode=2 (active detection).

  1. Use the search functionality (Cmd + f or Ctrl + f) to find “apiKey”. Screenshot included below but exact line number is subject to updates. Configure the Worker
  2. Paste the API key shared with you between the quotations after “apiKey:”. Important: Make sure to not add any additional spaces or characters when you copy the API key between the quotation marks.
  3. Click “Save and Deploy.”

Note: Repeat the steps in this section for every Worker code you received from our team.

3. Configure the Route(s)

By default, Cloudflare assigns a specific URL path to the Worker outside of your domain. The format of this URL is {worker name}.{hostname}.Workers.dev. You need to change the path to capture the URL of the page where the tag is deployed as well as the URL of the page where the protected event submissions happens.

  1. Select your newly created Worker and disable the default route by clicking on the switch. Disable the default route
  2. In the pop-up window, select “Undeploy.”
  3. Go back to the “Workers” page. Go back to Workers page
  4. Click on “Add Route.” Add Route Note: workers can be associated to routes with the following rules:
  5. In the following screen, define the route on which you would like the Worker to run. Define the Route Important: as a best practice, avoid a dangling “/” at the end of the configured route.

    Example: route test.com/exampleform/* should be configured as test.com/exampleform*
  6. Then, select the appropriate Worker for the defined route.
  7. Click on “Save.”

Note: Repeat the steps in this section for every Worker code you received from our team.

Integration Validation

Once the Cloudflare Worker code is deployed, it is important to validate that the script is running properly and the protected event submission loading as expected.

  1. Visit the webpage where the code was deployed by navigating to the page in all allowable ways (i.e direct url, a button, referral link) and by leveraging the following methods:
    • Normal mode
    • Incognito mode
    • Cleared browser local cache (to ensure the updated version of the website is retrieved)
    • Multiple browsers (ex: Chrome, Safari, Firefox)
  2. Each time, fill in the protected form on the webpage.
  3. Submit the form; it should behave as expected.
    • If an error message is displayed, please contact your representative for troubleshooting support.
  4. Check on your backend that the data upon form submission is obtained as expected.
    • If it isn’t so, please contact your representative for troubleshooting support.
  5. A couple of hours after you have deployed the code (at least 1 hour), check your Cloudflare metrics to ensure you are seeing successful events and subrequests coming through, but no errors.

Integration Validation

Note: Repeat the steps in this section for every Worker code you received from our team.

Monitoring and Billing

Cloudflare offers a Worker dashboard to monitor the number of queries that go through the Worker. Specific information on the graphs can be found here.

Under the Requests graph, you can find the total number of requests handled by the Worker. The number of Subrequests should always be higher than the number of Success because Subrequests will sum both the requests to the customer server and the Vesper API calls, while Success will just report the total number of queries to the customer server.

Note: Cloudflare Workers are included in every plan, however Cloudflare has some limitations for this technology: * Workers that receive over 100k requests per day will be disabled. * There is a maximum of 30 Workers per plan.