---
title: Getting started with client challenges
summary: null
url: >-
  https://www.fastly.com/documentation/guides/security/client-challenges/getting-started-with-client-challenges
---

Client challenges are security tasks that verify users are human or accessing your web application through a legitimate browser. You can use them with our [Bot Management](https://www.fastly.com/documentation/guides/security/bot-management/about-bot-management) or [Fastly DDoS Protection](https://www.fastly.com/documentation/guides/security/ddos-protection/about-ddos-protection) product to block unwanted bot traffic.

## Prerequisites

Before you set up client challenges, select the tab for the product you want to use and make sure you meet the requirements.

### Bot Management

Before setting up client challenges for Bot Management, you must:

- purchase the required products for your Bot Management deployment option. Pre-cache inspection requires [Bot Management](https://docs.fastly.com/products/bot-management). Post-cache inspection requires Bot Management and [Next-Gen WAF](https://docs.fastly.com/products/fastly-next-gen-waf) (Edge WAF deployment only).
- [deploy Bot Management](https://www.fastly.com/documentation/guides/security/bot-management/about-bot-management/#deploying-bot-management) on each CDN service where you intend to use client challenges. Compute services are not supported.

### DDoS

Before setting up client challenges for Fastly DDoS Protection, you must purchase [Fastly DDoS Protection](https://docs.fastly.com/products/fastly-ddos-protection) for your account.

## Limitations and considerations

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

- Don't manipulate the `Set-Cookie` response header or the `Cookie` request header in VCL, as these headers are essential for identifying initiated and solved challenges via the `_fs_ch_st_` and `_fs_ch_cp_` cookies.
- Don't cache the client challenge response. By default, Fastly honors the `Cache-Control: private, no-store` response header set on challenge responses, but custom VCL or configuration that overrides this behavior will cause errors for users attempting to access the challenged page.
- Private Access Token (PAT) challenges can only be issued to Apple-supported devices using iOS 16 or higher or macOS Ventura or higher.
- Client challenges may fail to load due to browser extensions, network issues, or restrictive settings, such as disabled cookies or blocked scripts. To resolve this, ask users to check their connection, disable ad blockers, or try a different browser.

Additionally, if you've deployed Bot Management with post-cache inspection, keep in mind the following:

- Client challenges are issued to fully-qualified domain names (FQDN). If your service includes subdomains that shouldn't receive challenges (e.g., api.example.com), be sure to restrict the challenge to the desired subdomains when creating the request rule that adds the challenge.
- To [exclude a bot from client challenges](https://www.fastly.com/documentation/guides/security/client-challenges/serving-challenges-with-interstitial-pages) 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).

## Quick start

To protect your web application from unwanted bot traffic, you can configure Bot Management or Fastly DDoS Protection to issue client challenges. While Fastly offers different [types of challenges](https://www.fastly.com/documentation/guides/security/client-challenges/how-client-challenges-work/#challenge-types) depending on the product you're using, this section only covers the steps for serving dynamic challenges on [interstitial pages](https://en.wikipedia.org/wiki/Interstitial_webpage).

> **HINT:** Don't want to serve dynamic challenges to an interstitial page? Try one of these options instead:
>
> - [embed a dynamic challenge](https://www.fastly.com/documentation/guides/security/client-challenges/embedding-dynamic-challenges-in-pages) in a React or single-page application.
> - [send only interactive or non-interactive challenges](https://www.fastly.com/documentation/guides/security/client-challenges/serving-challenges-with-interstitial-pages) if you've deployed Bot Management with post-cache inspection.

With a dynamic challenge, Fastly chooses the most-appropriate type of challenge to send to the client. To minimize disruption to your application's user experience, Fastly will only serve interactive challenges (e.g., CAPTCHA) when suspicious activity is detected. Otherwise, Fastly will send non-interactive challenges (e.g., JavaScript proof-of-work).

To set up client challenges, select the tab for the product you want to use and follow the instructions.

### Bot Management (pre-cache inspection)

If you've deployed Bot Management with pre-cache inspection (ContentGuard), start by selecting the bot categories or identities you want to challenge. Bot Management groups bots into categories (e.g., search engines, AI crawlers). Within each category, individual bots are tracked as identities (e.g., Googlebot). You can set actions at either level.

1.   Log in to the [Fastly control panel](https://manage.fastly.com).

2. Go to **Security** > **Bot Management** > **Protection**.
3.   From the services menu, select the appropriate service.

4. In the row of the bot category that you'd like to configure protection for, do one of the following:

   - From the **Action** menu, select **Challenge**. Fastly will challenge all bot identities that are included in that category.
   - Click **Configure bots** and then from the **Action** menu for the relevant bot identities, select **Challenge**. Fastly will challenge these bots.

Next, change your Protection mode to **Block (Active enforcement)** to enforce the bot category and identity actions you selected on the Protection page.

1.   Log in to the [Fastly control panel](https://manage.fastly.com).

2. Go to **Security** > **Bot Management** > **Settings**.
3.   From the services menu, select the appropriate service.

4. From the **Protection mode** menu, select **Block (Active enforcement)**.

After setting up Bot Management to challenge select bot categories and identities, you can optionally:

- [add a custom logo](https://www.fastly.com/documentation/guides/security/client-challenges/adding-custom-logos-to-interstitial-pages) to the interstitial page where the challenge will be served.
- configure the challenge to be [embedded within a page](https://www.fastly.com/documentation/guides/security/client-challenges/embedding-dynamic-challenges-in-pages) of your web application, rather than served on an interstitial page.

### Bot Management (post-cache inspection)

If you've deployed Bot Management with post-cache inspection (Next-Gen WAF), you can protect specific endpoints with a dynamic challenge by creating rules in the Next-Gen WAF that do the following:

1. Send the challenge.
2. Verify the challenge token.
3. Block requests with invalid tokens.

The following instructions show how to set up these rules for `www.example.com/login`. Be aware that this example uses values (e.g., hostnames and paths) that may not be the same as those used by your particular web application.

### Send the challenge

First, create a rule that challenges all traffic destined for `www.example.com/login`:

1.   Log in to the [Fastly control panel](https://manage.fastly.com).

2.   Go to **Security** > **Next-Gen WAF** > [**Rules**](https://manage.fastly.com/security/ngwaf/rules).

3.   From the workspaces bar, click the menu <span class="inline-icons"><img src="/img/icons/chevron-down.png" alt="Menu icon" /></span> to the right of the workspace name and select a workspace.

4. Click **Add workspace rule**.

5. In the **Type** area, select **Request**.

6. In the **Conditions** area, define where the rule should send the challenge. For example, to send a challenge to all request traffic destined for `www.example.com/login`, create the following conditions:

   | Condition | Field  | Operator | Value             |
   | --------- | ------ | -------- | ----------------- |
   | 1         | Method | Equals   | GET               |
   | 2         | Domain | Equals   | `www.example.com` |
   | 3         | Path   | Equals   | `/login`          |

7. In the **Actions** area, select [**Dynamic challenge**](https://www.fastly.com/documentation/guides/next-gen-waf/rules/about-rules/#action-types) from the **Action type** menu.

8. Fill out the fields in the **Details** area as follows:
   - In the **Description** field, enter a description for the rule.
   - Leave the **Status** switch for the rule enabled.

9. Click **Create workspace rule**.

### Verify the token

Next, create a rule to verify whether clients have a valid token from correctly solving a challenge. You need to create this rule so that you can block requests with invalid tokens in the next step.

1. Click **Add workspace rule**.

   ![A request rule designed to verify the token on POST requests to www.example.com/login.](/img/ngwaf/verify-token-rule-in-fcp.png)

2. Add the following three conditions to ensure the WAF only applies this rule to HTTP POST requests where the domain is `www.example.com` and the request path is `/login`.

   | Condition | Field  | Operator | Value             |
   | --------- | ------ | -------- | ----------------- |
   | 1         | Method | Equals   | POST              |
   | 2         | Domain | Equals   | `www.example.com` |
   | 3         | Path   | Equals   | `/login`          |

3. Add the following condition to ensure the WAF does not apply this rule to requests made by [verified bots](https://www.fastly.com/documentation/guides/next-gen-waf/signals/using-system-signals/#bots).

   - From the first **Field** menu, select **Signal**.
   - From the first **Operator** menu, select **Does not exist where**.
   - From the second **Field** menu, select **Signal ID**.
   - From the second **Operator** menu, select **Equals**.
   - From the **Value** menu, select **Verified Bot**.

4. From the **Type** menu in the **Actions** section, select [**Verify token**](https://www.fastly.com/documentation/guides/next-gen-waf/rules/about-rules/#action-types) to check whether the client has successfully solved a challenge on a previous request.

5. In the **Description** field, enter `Verify token on POST requests to www.example.com/login`.

6. Click **Create workspace rule**.

### Block requests with invalid tokens

> **IMPORTANT:** Before creating this rule, [create a custom signal](https://www.fastly.com/documentation/guides/next-gen-waf/signals/working-with-custom-signals/#creating-custom-signals) named `Login attempt with invalid token`.

Finally, create a rule to block requests from clients that don't have a valid token:

1. Click **Add workspace rule**.

   ![A request rule designed to block requests to www.example.com/login when the client hasn't solved a previous challenge.](/img/ngwaf/block-login-with-invalid-token-rule-in-fcp.png)

2. Add the following three conditions to ensure the WAF only applies this rule to HTTP POST requests where the domain is `www.example.com` and the request path is `/login`.

   | Condition | Field  | Operator | Value             |
   | --------- | ------ | -------- | ----------------- |
   | 1         | Method | Equals   | POST              |
   | 2         | Domain | Equals   | `www.example.com` |
   | 3         | Path   | Equals   | `/login`          |

3. Add the following conditions to ensure the WAF only applies this rule to requests tagged with the `CHALLENGE-TOKEN-INVALID` signal.

   - From the first **Field** menu, select **Signal**.
   - From the first **Operator** menu, select **Exists where**.
   - From the second **Field** menu, select **Signal ID**.
   - From the second **Operator** menu, select **Equals**.
   - From the **Value** menu, select **Challenge Token Invalid**.

4. From the **Type** menu in the **Actions** section, select **Block**.

5. Click **Add action**. New menus appear.

6. From the new **Action type** menu, select **Add signal** and from the **Signal** menu, select the `Login attempt with invalid token` custom signal.

7. In the **Description** field, enter `Block requests to www.example.com/login when the client hasn't solved a previous challenge.`.

8. Click **Create workspace rule**.

After setting up Bot Management to use client challenges to protect an endpoint, you can optionally [add a custom logo](https://www.fastly.com/documentation/guides/security/client-challenges/adding-custom-logos-to-interstitial-pages) to the interstitial page where the challenge will be served.

### DDoS

To start issuing dynamic challenges to clients that DDoS Protection identifies as attack traffic, follow these steps:

1.   Log in to the [Fastly control panel](https://manage.fastly.com).

2.   From the [**Home**](https://manage.fastly.com/home) page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3. Click **Service configuration**.
4. In the **Security** area, click the **DDoS Protection** switch to **On** to immediately enable DDoS Protection for this service.
5. From the **Protection mode** menu, select **Challenge**.

After setting up Fastly DDoS Protection to challenge attack traffic, you can optionally:

- [add a custom logo](https://www.fastly.com/documentation/guides/security/client-challenges/adding-custom-logos-to-interstitial-pages) to the interstitial page where the challenge will be served.
- configure the challenge to be [embedded within a page](https://www.fastly.com/documentation/guides/security/client-challenges/embedding-dynamic-challenges-in-pages) of your web application, rather than served on an interstitial page.
- [override the protection mode](https://www.fastly.com/documentation/guides/security/ddos-protection/about-the-ddos-protection-controls) for specific rules

## Related content

### Bot Management (pre-cache inspection)

- [Adding custom logos to interstitial pages](https://www.fastly.com/documentation/guides/security/client-challenges/adding-custom-logos-to-interstitial-pages)
- [Embedding dynamic challenges in pages](https://www.fastly.com/documentation/guides/security/client-challenges/embedding-dynamic-challenges-in-pages)
- [Managing bot traffic](https://www.fastly.com/documentation/guides/security/bot-management/contentguard/managing-bot-traffic)
- [Monitoring bot traffic](https://www.fastly.com/documentation/guides/security/bot-management/contentguard/monitoring-bot-traffic)

### Bot Management (post-cache inspection)

- [Embedding dynamic challenges in pages](https://www.fastly.com/documentation/guides/security/client-challenges/embedding-dynamic-challenges-in-pages)
- [Serving challenges with interstitial pages](https://www.fastly.com/documentation/guides/security/client-challenges/serving-challenges-with-interstitial-pages)
- [Adding custom logos to interstitial pages](https://www.fastly.com/documentation/guides/security/client-challenges/adding-custom-logos-to-interstitial-pages)
- [Blocking requests with invalid challenge tokens](https://www.fastly.com/documentation/guides/security/client-challenges/blocking-requests-with-invalid-challenge-tokens)

### DDoS

- [About the DDoS protection controls](https://www.fastly.com/documentation/guides/security/ddos-protection/about-the-ddos-protection-controls)
- [Adding custom logos to interstitial pages](https://www.fastly.com/documentation/guides/security/client-challenges/adding-custom-logos-to-interstitial-pages)
- [Embedding dynamic challenges in pages](https://www.fastly.com/documentation/guides/security/client-challenges/embedding-dynamic-challenges-in-pages)