Using client challenges

Sites (also known as workspaces) can be set up to send either interactive or non-interactive challenges to clients and those challenges can be conditionally exempted with the appropriate rules configuration.

Before you begin

Using client challenges requires the purchase of the Bot Management product at either the Professional or Premier platform level (it is not available for the Essential platform). Once purchased, client challenges must be enabled for each individual service using your service ID before you can configure them as request rules.

Limitations and considerations

When working with client challenges, keep the following things in mind:

• You must choose between either an interactive or non-interactive challenge for each service. Both cannot be active on a single service at the same time.
• Using client challenges for multiple hostnames within the same service requires rule conditions to restrict the challenge to a specific hostname. If, for example, a service includes both www.example.com and api.example.com as hosts, client challenges will not behave as expected. We suggest restricting client challenges to a specific hostname.
• To exclude a bot from client challenges when you want it to access your website, you must include that bot in a rule condition (e.g., set up a rule condition excluding clients with the VERIFIED-BOT signal from client challenges).

Available challenges and how they work

Two types of challenges are available to send to clients:

• Non-interactive challenges leverage what is called a JavaScript proof-of-work and ask a client to prove that it is running a JavaScript-compatible browser by solving what is essentially a JavaScript math problem.
• Interactive challenges (sometimes called CAPTCHA challenges) prompt a client with a random alphanumeric string and ask the client to enter that string into the presented box to prove that the person requesting the information is human.

Challenged requests are tagged with the Challenged Request (CHALLENGED) signal and either the Challenge Token Valid (CHALLENGE-TOKEN-VALID) or Challenge Token Invalid (CHALLENGE-TOKEN-INVALID) signal.

Enabling client challenges

Once you've obtained access to Bot Management features, send the following Fastly enablement API call for each service you plan to use client challenges on, replacing <SID> with your service ID:

PUT /enabled-products/bot_management/services/<SID>

Example client challenges

The following examples demonstrate how to configure client challenges for a few common use cases. Be sure to change the generic values (e.g., hostnames and paths) in these examples to ones specific to your particular application.

Requiring a challenge for all traffic except from verified bots

Let's say you want to create a rule that sends a challenge to all request traffic destined for www.example.com/challenge except for requests with the VERIFIED-BOT signal. When configuring the request rule, create three conditions as follows, making sure to select All so that they are all true:

In the control panel, the settings would appear like this:

Then create a condition group for the challenge itself by clicking Add condition from below the first three conditions, and then specifying the settings of that condition as follows:

• From the first Field menu, select Signal.
• From the first Operator menu, select Does not exist where.
• Select All to specify that a request must meet every condition.
• From the second Field menu, select Signal Type.
• From the second Operator menu, select Equals.
• From the Value menu, select Verified Bot.

In the control panel, the settings would appear like this:

Then decide whether you want the challenge to be interactive or non-interactive by:

• From the Action type menu, select Browser challenge.
• Click the Allow Interactive switch to require an interactive (CAPTCHA) challenge setting or leave it disabled to keep the challenge non-interactive.

In the control panel, the settings for an interactive challenge would look like this:

Protecting a POST endpoint

Let's say you want to create rules that protect a POST endpoint, in this case www.example.com/login. To do this, configure three request rules that would:

• send a browser challenge for any GET requests,
• use token verification on a POST request, and
• configure signal blocking for requests that are invalid.

Creating a browser challenge

When configuring the browser challenge rule, create three conditions as follows, making sure to select All to require them to all be true:

In the control panel, the settings would appear like this:

Then create a condition group for the challenge itself by clicking Add condition from below the first three conditions, and then specifying the settings of that condition as follows:

• From the first Field menu, select Signal.
• From the first Operator menu, select Does not exist where.
• Select All to specify that a request must meet every condition.
• From the second Field menu, select Signal Type.
• From the second Operator menu, select Equals.
• From the Value menu, select Verified Bot.

In the control panel, the settings would appear like this:

Then select the browser challenge by doing this:

• From the Action type menu, select Browser challenge.
• Leave the Allow Interactive switch disabled to keep the challenge non-interactive.

In the control panel, the non-interactive challenge setting would look like this:

Configuring token verification

When configuring the token verification rule, create three conditions as follows, making sure to select All to require them to all be true:

In the control panel, the settings would appear like this:

Then create a condition group for the challenge itself by clicking Add condition from below the first three conditions, and then specifying the settings of that condition as follows:

• From the first Field menu, select Signal.
• From the first Operator menu, select Does not exist where.
• Select All to specify that a request must meet every condition.
• From the second Field menu, select Signal Type.
• From the second Operator menu, select Equals.
• From the Value menu, select Verified Bot.

In the control panel, the settings would appear like this:

Then from the Action type menu, select Verify token to set the browser challenge.

In the control panel, the non-interactive challenge setting would look like this:

Configuring signal blocking

When configuring the signal blocking rule, create two conditions as follows, making sure to select All to require them to all be true:

In the control panel, the settings would appear like this:

Then create a condition group for the challenge itself by clicking Add condition from below the first two conditions, and then specifying the settings of that condition as follows:

• From the first Field menu, select Signal.
• From the first Operator menu, select Exists where.
• Select All to specify that a request must meet every condition.
• From the second Field menu, select Signal Type.
• From the second Operator menu, select Equals.
• From the Value menu, select Challenge Token Invalid.

In the control panel, the settings would appear like this:

Then select the browser challenge by doing this:

• From the Action type menu, select Browser challenge.
• Leave the Allow Interactive switch disabled to keep the challenge non-interactive.

In the control panel, the non-interactive challenge setting would look like this: