diff --git a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages.mdx b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages.mdx deleted file mode 100644 index 517f3825f7d4466..000000000000000 --- a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -pcx_content_type: concept -title: Challenge pages -sidebar: - order: 1 ---- - -The types of available challenge pages function similarly. The main difference between the challenges are when and if an interaction is presented to the visitor. - -- Managed challenges will rarely present the visitor with an interactive challenge, except in cases where Cloudflare cannot verify the legitimacy of the visitor. -- JavaScript challenges never present the visitor with an interactive challenge. -- Interactive challenges present the visitor with a simple and solvable challenge, such as selecting a checkbox, to verify their legitimacy. - -Refer to the information below for more details on available challenges. - -## Available challenges - -### Managed challenge (recommended) - -Managed challenges are where Cloudflare dynamically chooses the appropriate type of challenge based on the characteristics of a request. This helps avoid [CAPTCHAs](https://www.cloudflare.com/learning/bots/how-captchas-work/), which also reduces the lifetimes of human time spent solving CAPTCHAs across the Internet. - -Unless there are specific compatibility issues or other reasons to use other types of challenges, you should use managed challenges for your various custom rules. - -:::caution -Using Cloudflare challenges along with Rules features may cause challenge loops. Refer to [Rules troubleshooting](/rules/reference/troubleshooting/) for more information. -::: - -### JavaScript challenge - -With a JavaScript (JS) challenge, Cloudflare presents a challenge page that requires no interaction from a visitor except the JavaScript processed by their browser. - -The visitor must wait until their browser finishes processing the JavaScript, which should be less than five seconds. - -### Interactive challenge - -Interactive challenges require a visitor to interact with the interstitial challenge page, presenting the visitor with an interactive challenge to solve. Cloudflare does not recommend using Interactive Challenges. -For more on why Cloudflare does not recommend using Interactive Challenge, in favor of Managed Challenge, refer to our [blog post](https://blog.cloudflare.com/end-cloudflare-captcha/). - ---- - -## Detect a challenge page response - -When a request encounters a Cloudflare challenge page instead of the originally anticipated response, the challenge page response (regardless of the challenge page type) will have the `cf-mitigated` header present and set to `challenge`. This header can be leveraged to detect if a response was challenged when making fetch/XHR requests. This header provides a reliable way to identify whether a response is a challenge or not, enabling a web application to take appropriate action based on the result. For example, a front-end application encountering a response from the backend may check the presence of this header value to handle cases where challenge pages encountered unexpectedly. - -:::note -Regardless of the requested resource-type, the content-type of a challenge will be `text/html`. -::: - -For the `cf-mitigated` header, `challenge` is the only valid value. The header is set for all challenge page types. - -To illustrate, here is a JavaScript code snippet that demonstrates how to use the `cf-mitigated` header to detect whether a response was challenged: - -```js -fetch("/my-api-endpoint").then((response) => { - if (response.headers.get("cf-mitigated") === "challenge") { - // Handle challenged response - } else { - // Process response as usual - } -}); -``` - -For additional help, refer to our [FAQ](/cloudflare-challenges/troubleshooting/frequently-asked-questions/). - ---- - -## Resolve a challenge - -If a visitor encounters a challenge, Cloudflare employees cannot remove that challenge. Only the website owner can configure their Cloudflare settings to stop the challenge being presented. - -When observing a Cloudflare Challenge page, a visitor could: - -- Successfully pass the challenge to visit the website. -- Request the website owner to allow their IP address. -- Scan their computer for malicious programs (it may be infected). -- Check their antivirus or firewall service to make sure it is not blocking access to the challenge resources (for example, images). - -:::note -Visitors must enable JavaScript and cookies on their browser to be able to pass any type of challenge. -::: - ---- - -## Challenge Passage - -When a visitor solves a [Cloudflare challenge](/cloudflare-challenges/) - as part of a [WAF custom rule](/waf/custom-rules/) or [IP Access rule](/waf/tools/ip-access-rules/) - you can set the **Challenge Passage** to prevent them from having to solve future challenges for a specified period of time. - -### How it works - -When a visitor successfully solves a challenge, Cloudflare sets a [`cf_clearance` cookie](/fundamentals/reference/policies-compliances/cloudflare-cookies/#additional-cookies-used-by-the-challenge-platform) in their browser. This cookie specifies the duration your website is accessible to that visitor. - -When that visitor tries to access other parts of your website, Cloudflare evaluates the cookie before presenting another challenge. If the cookie is still valid, no challenges will be shown. - -When Cloudflare evaluates a `cf_clearance` cookie, a few extra minutes are included to account for clock skew. For XmlHTTP requests, an extra hour is added to the validation time to prevent breaking XmlHTTP requests for pages that set short lifetimes. - -### Customize the Challenge Passage - -By default, the `cf_clearance` cookie has a lifetime of 30 minutes. Cloudflare recommends a setting between 15 and 45 minutes. - -To update the Challenge Passage (and the value of the `cf_clearance` cookie): - -1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com). -2. Select your account and domain. -3. Go to **Security** > **Settings**. -4. For **Challenge Passage**, select a duration. - -### Limitations - -The Challenge Passage does not apply to challenges issued by WAF managed rules. Also, Challenge Passage does not apply to rate limiting rules unless the rate limit is configured to issue a challenge. - ---- - -## Additional configuration - -### Multi-language support - -Refer to [supported languages](/cloudflare-challenges/reference/supported-languages/) for more information. - -### Favicon customization - -Cloudflare challenges take the favicon of your website using `GET /favicon.ico` and displays it on the challenge page. - -You can customize your favicon by using the HTML snippet below. - -```html title="HTML element" - -``` \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/additional-configuration.mdx b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/additional-configuration.mdx new file mode 100644 index 000000000000000..77eebbec96e50fb --- /dev/null +++ b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/additional-configuration.mdx @@ -0,0 +1,20 @@ +--- +pcx_content_type: concept +title: Additional configuration +sidebar: + order: 6 +--- + +## Multi-language support + +Refer to [supported languages](/cloudflare-challenges/reference/supported-languages/) for more information. + +## Favicon customization + +Cloudflare Challenges take the favicon of your website using `GET /favicon.ico` and displays it on the Challenge Page. + +You can customize your favicon by using the HTML snippet below. + +```html title="HTML element" + +``` \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/challenge-passage.mdx b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/challenge-passage.mdx new file mode 100644 index 000000000000000..99dd1f7502d660f --- /dev/null +++ b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/challenge-passage.mdx @@ -0,0 +1,32 @@ +--- +pcx_content_type: concept +title: Challenge Passage +sidebar: + order: 3 +--- + + +When a visitor solves a [Cloudflare Challenge](/cloudflare-challenges/) - as part of a [WAF custom rule](/waf/custom-rules/) or [IP Access rule](/waf/tools/ip-access-rules/) - you can set the **Challenge Passage** to prevent them from having to solve future Challenges for a specified period of time. + +### How it works + +When a visitor successfully solves a Challenge, Cloudflare sets a [`cf_clearance` cookie](/fundamentals/reference/policies-compliances/cloudflare-cookies/#additional-cookies-used-by-the-challenge-platform) in their browser. This cookie specifies the duration your website is accessible to that visitor. + +When that visitor tries to access other parts of your website, Cloudflare evaluates the cookie before presenting another Challenge. If the cookie is still valid, no Challenges will be shown. + +When Cloudflare evaluates a `cf_clearance` cookie, a few extra minutes are included to account for clock skew. For XmlHTTP requests, an extra hour is added to the validation time to prevent breaking XmlHTTP requests for pages that set short lifetimes. + +### Customize the Challenge Passage + +By default, the `cf_clearance` cookie has a lifetime of 30 minutes. Cloudflare recommends a setting between 15 and 45 minutes. + +To update the Challenge Passage (and the value of the `cf_clearance` cookie): + +1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com). +2. Select your account and domain. +3. Go to **Security** > **Settings**. +4. For **Challenge Passage**, select a duration. + +### Limitations + +The Challenge Passage does not apply to Challenges issued by [WAF managed rules](/waf/managed-rules/). Also, Challenge Passage does not apply to rate limiting rules unless the rate limit is configured to issue a Challenge. diff --git a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/create-custom-rule.mdx b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/create-custom-rule.mdx new file mode 100644 index 000000000000000..160a850a2e44cfc --- /dev/null +++ b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/create-custom-rule.mdx @@ -0,0 +1,14 @@ +--- +pcx_content_type: how-to +title: Implement a Challenge Page via WAF custom rules +sidebar: + order: 2 + label: Implementation +--- + +import { Render } from "~/components" + + + +- **Bot Management**: You can set the custom rule to challenge a visitor based on the [bot score](/bots/concepts/bot-score/) or [detection ID](/bots/additional-configurations/detection-ids/). +- **Rate limiting**: You can challenge visitors based on your defined rate limits. \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/detect-response.mdx b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/detect-response.mdx new file mode 100644 index 000000000000000..474b24f839c941c --- /dev/null +++ b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/detect-response.mdx @@ -0,0 +1,30 @@ +--- +pcx_content_type: concept +title: Detect a Challenge Page response +sidebar: + order: 4 +--- + +## Detect a Challenge Page response + +When a request encounters a Cloudflare Challenge Page instead of the originally anticipated response, the Challenge Page response (regardless of the Challenge Page type) will have the `cf-mitigated` header present and set to `challenge`. This header can be leveraged to detect if a response was challenged when making fetch/XHR requests. This header provides a reliable way to identify whether a response is a Challenge or not, enabling a web application to take appropriate action based on the result. For example, a front-end application encountering a response from the backend may check the presence of this header value to handle cases where Challenge Pages encountered unexpectedly. + +:::note +Regardless of the requested resource-type, the content-type of a Challenge will be `text/html`. +::: + +For the `cf-mitigated` header, `challenge` is the only valid value. The header is set for all Challenge Page types. + +To illustrate, here is a JavaScript code snippet that demonstrates how to use the `cf-mitigated` header to detect whether a response was challenged: + +```js +fetch("/my-api-endpoint").then((response) => { + if (response.headers.get("cf-mitigated") === "challenge") { + // Handle challenged response + } else { + // Process response as usual + } +}); +``` + +For additional help, refer to our [FAQ](/cloudflare-challenges/frequently-asked-questions/). diff --git a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/index.mdx b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/index.mdx new file mode 100644 index 000000000000000..37e6f932922548f --- /dev/null +++ b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/index.mdx @@ -0,0 +1,45 @@ +--- +pcx_content_type: concept +title: Interstitial Challenge Pages +sidebar: + order: 1 +--- +import { Render } from "~/components" + +An interstitial Challenge Page acts as a gate between the visitor and your website or application while Cloudflare verifies the authenticity of the visitor. + +The Challenge Page intercepts the visitor from getting to the destination URL by holding the request and evaluating the browser environment for automated signals, and serving a Challenge. The visitor cannot reach their destination without passing the Challenge. Based on the signals indicated by their browser environment, the visitor may be asked to perform an interaction such as checking a box or selecting a button for further probing. + + + +The level of interactivity and visibility of the Challenge Page depends on the Action that you select when creating the WAF rule for your website or application. + +## Actions + +The following Challenge types are the available actions when you create a WAF rule for a Challenge Page. + +### Managed Challenge (recommended) + +Managed Challenges are where Cloudflare dynamically chooses the appropriate type of Challenge served to the visitor based on the characteristics of a request from the signals indicated by their browser. This helps avoid [CAPTCHAs](https://www.cloudflare.com/learning/bots/how-captchas-work/), which also reduces the lifetimes of human time spent solving CAPTCHAs across the Internet. + +Most human visitors are automatically verified and the Challenge Page will display **Successful**. However, if Cloudflare detects non-human attributes from the visitor's browser, they may be required to interact with the Challenge to solve it. + +Unless there are specific compatibility issues or other reasons to use other types of Challenges, Cloudflare recommends you to use Managed Challenges for your custom rules. + +:::caution +Using Cloudflare Challenges along with Rules features may cause Challenge loops. Refer to [Rules troubleshooting](/rules/reference/troubleshooting/) for more information. +::: + +### Interactive Challenge + +Interactive Challenge Pages offer the highest security for your website or application because it requires a visitor to interact with the Interstitial Challenge Page, presenting the visitor with an Interactive Challenge to solve. + +For more information about why Cloudflare does not recommend using Interactive Challenge, in favor of Managed Challenge, refer to our [blog post](https://blog.cloudflare.com/end-cloudflare-captcha/). + +### JavaScript Challenge (non-interactive) + +With a JavaScript (JS) Challenge, Cloudflare makes the determination on whether or not the visitor is automated based on the limited information attained from their browser signals via an injected JavaScript. Then, it presents a Challenge Page that requires no interaction from a visitor except the JavaScript processed by their browser. + +The visitor must wait until their browser finishes processing the JavaScript, which typically takes less than five seconds. + +If the visitor passes the Challenge, the original request continues to the destination URL. If the Challenge fails or cannot be completed, the visitor is presented with another Interstitial Challenge Page. \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/resolve-challenge.mdx b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/resolve-challenge.mdx new file mode 100644 index 000000000000000..88983d15c6f2324 --- /dev/null +++ b/src/content/docs/cloudflare-challenges/challenge-types/challenge-pages/resolve-challenge.mdx @@ -0,0 +1,19 @@ +--- +pcx_content_type: concept +title: Resolve a Challenge +sidebar: + order: 5 +--- + +If a visitor encounters a Challenge, Cloudflare employees cannot remove that Challenge. Only the website owner can configure their Cloudflare settings to stop the Challenge being presented. + +When observing a Cloudflare Challenge page, a visitor could: + +- Successfully pass the Challenge to visit the website. +- Request the website owner to allow their IP address. +- Scan their computer for malicious programs (it may be infected). +- Check their antivirus or firewall service to make sure it is not blocking access to the Challenge resources (for example, images). + +:::note +Visitors must enable JavaScript and cookies on their browser to be able to pass any type of Challenge. +::: \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/challenge-types/index.mdx b/src/content/docs/cloudflare-challenges/challenge-types/index.mdx index 84eb3f3fde2e46a..4e9db8d2190093e 100644 --- a/src/content/docs/cloudflare-challenges/challenge-types/index.mdx +++ b/src/content/docs/cloudflare-challenges/challenge-types/index.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: navigation -title: Challenge types +title: Available Challenges sidebar: order: 3 group: @@ -9,6 +9,6 @@ sidebar: import { DirectoryListing } from "~/components" -Refer to the following pages for more information on available challenge types: +Refer to the following pages for more information on available Challenge types: \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/challenge-types/javascript-detections.mdx b/src/content/docs/cloudflare-challenges/challenge-types/javascript-detections.mdx index 6134c98fa8ae2d4..c6aeea9e0174697 100644 --- a/src/content/docs/cloudflare-challenges/challenge-types/javascript-detections.mdx +++ b/src/content/docs/cloudflare-challenges/challenge-types/javascript-detections.mdx @@ -4,7 +4,7 @@ type: overview pcx_content_type: reference title: JavaScript detections sidebar: - order: 6 + order: 3 --- import { Render } from "~/components" diff --git a/src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx b/src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx new file mode 100644 index 000000000000000..5bef2f1c14f0365 --- /dev/null +++ b/src/content/docs/cloudflare-challenges/challenge-types/turnstile.mdx @@ -0,0 +1,38 @@ +--- +pcx_content_type: concept +title: Turnstile +sidebar: + order: 2 +--- + +import { Render } from "~/components"; + +[Turnstile](/turnstile/) is Cloudflare's CAPTCHA-alternative solution. You can embed Turnstile as a widget on your website or application, where it runs a client-side Challenge directly in the background of the visitor's browser. + +Turnstile differs from Challenges Pages in that the Challenge does not pause the request or interrupt the user's experience. Since the widget is embedded onto the webpage and only runs on a specific part of the HTML, the visitor will have already arrived at the destination URL and is viewing the page when they encounter a Turnstile widget. Instead of blocking the visitor from accessing the entire website, the Turnstile widget prevents the visitor from certain actions such as completing login or sign up forms, and more, until the widget is solved. + +In most cases, nothing further is required from the visitor. However, if necessary, Turnstile may display a simple checkbox that the visitor must click to proceed. + +After the Challenge passes, Turnstile issues a clearance token to the visitor that must be validated via the [Siteverify API](/turnstile/get-started/server-side-validation/) before completing a sensitive action like login, sign up, or other form submissions. + + + +## Widget types + +While there are three types of widgets that you can choose to implement on your website or application, the Challenge logic behind them remains the same. + +- **Managed (recommended)**: Functions similar to a Managed Challenge Page. It selects a Challenge based on the signals gathered from the visitor's browser and presents an interaction only if it detects potentially automated traffic. + +- **Non-Interactive**: The widget is displayed, but the visitor does not need to interact with it to verify their identity. + +- **Invisible**: The widget is completely invisible to the visitor, but the Challenge still runs in the background. + +## Implementation + +When you create a widget for your website or application via the Cloudflare dashboard, you will receive a sitekey. + +The sitekey is used with [client-side rendering](/turnstile/get-started/client-side-rendering/#implicitly-render-the-turnstile-widget) by adding it to the `
` container placeholder. You will then place that `
` code snippet where you want to add the widget to your site page or form. + +## Get started + +Refer to the [Turnstile documentation](/turnstile/get-started/) for guidance on implementing a widget to your website or application. \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/concepts/clearance.mdx b/src/content/docs/cloudflare-challenges/concepts/clearance.mdx new file mode 100644 index 000000000000000..02bba828835f21f --- /dev/null +++ b/src/content/docs/cloudflare-challenges/concepts/clearance.mdx @@ -0,0 +1,71 @@ +--- +pcx_content_type: concept +title: Clearance +sidebar: + order: 2 +--- +import { Render } from "~/components"; + +## `cf-clearance` cookies + +A `cf-clearance` cookie proves to Cloudflare that the visitor is a verified human and has passed the Challenge presented to them. + +If a visitor passes an Interactive Challenge (highest security level), then the `cf-clearance` cookie indicates this to the origin and allows the visitor to bypass any other Challenge on the website, whether it is another Interactive Challenge, a Managed Challenge, or a non-interactive JavaScript Challenge for as long as the cookie is valid. + +If a visitor receives a `cf-clearance` cookie on a page that uses a WAF rule with Managed or JavaScript Challenge (lower security levels), then encountering a different page with a higher security clearance level Challenge will prompt them to solve the Challenge again. + +The original `cf-clearance` cookie that was issued to the visitor from a lower security clearance level Challenge will be replaced with the new `cf-clearance` cookie from a higher security clearance level Challenge. + +## Pre-clearance support in Turnstile + +Pre-clearance in [Turnstile](/turnstile/) allows websites to streamline user experiences by using `cf-clearance` cookies. The `cf-clearance` cookie enables visitors to bypass WAF Challenges downstream, based on the security clearance level set by the customer. This can be particularly useful for trusted visitors, enhancing usability while maintaining security. + +By default, Turnstile issues a one-time use token to the visitor when they solve a Challenge via the widget. The token goes to your website's backend that needs to be validated by Siteverify API. + + + +:::note +The clearance token cannot be used again. +::: + +| Challenge type | Issued clearance | +| --- | --- | +| Challenge Page | `cf-clearance` cookie (default) +| Turnstile widget | Token (default)
`cf-clearance cookie` (optional addition) | + +When you enable pre-clearance support on Turnstile, a `cf-clearance` cookie is issued to the visitor in addition to the default Turnstile token. + +You can integrate Cloudflare Challenges by allowing Turnstile to issue a `cf-clearance` cookie as pre-clearance to your visitor. The pre-clearance level is set upon widget creation or widget modification using the Turnstile API's clearance_level. Possible values for the configuration are: + +- `interactive` +- `managed` +- `jschallenge` +- `no_clearance` + +All widgets have pre-clearance mode set to `false` and the security clearance is set to `no_clearance` by default. + +For Enterprise customers eligible to enable widgets without any pre-configured hostnames, Cloudflare recommends issuing pre-clearance cookies on widgets where at least one hostname is specified and is the same as the zone that you want to integrate with Turnstile. + +Refer to the [blog post](https://blog.cloudflare.com/integrating-turnstile-with-the-cloudflare-waf-to-challenge-fetch-requests) for more details on how pre-clearance works with WAF. + +### Pre-clearance level options + +**Interactive** (High) `interactive` + +Allows a user with a clearance cookie to not be challenged by Interactive, Managed Challenge, or JavaScript Challenge Firewall Rules. + +**Managed** (Medium) `managed` + +Allows a user with a clearance cookie to not be challenged by Managed Challenge or JavaScript Challenge Firewall Rules. + +**Non-interactive** (Low) `jschallenge` + +Allows a user with a clearance cookie to not be challenged by JavaScript Challenge Firewall Rules. + +### Clearance cookie duration + +Clearance cookies generated by the Turnstile widget will be valid for the time specified by the zone-level Challenge Passage value. To configure the Challenge Passage setting, refer to the [Cloudflare Challenges documentation](/cloudflare-challenges/challenge-types/challenge-pages/challenge-passage/). + +### Setup + +To set up pre-clearance cookies for Turnstile, refer to [Enable pre-clearance cookies](/turnstile/get-started/pre-clearance/). diff --git a/src/content/docs/cloudflare-challenges/concepts/how-challenges-work.mdx b/src/content/docs/cloudflare-challenges/concepts/how-challenges-work.mdx index 9c07e9a6915132a..9b2d65e9ae9e337 100644 --- a/src/content/docs/cloudflare-challenges/concepts/how-challenges-work.mdx +++ b/src/content/docs/cloudflare-challenges/concepts/how-challenges-work.mdx @@ -1,54 +1,43 @@ --- pcx_content_type: concept -title: How challenges work +title: How Challenges work sidebar: order: 1 + label: Challenges --- Challenges can be issued in three primary ways depending on which Cloudflare products or features are in use. Each method is designed to balance security with seamless visitor experience. | Product | Challenge type(s) | | --- | --- | -| [WAF](/waf/) ([custom rules](/waf/custom-rules/), [rate limiting rules](/waf/rate-limiting-rules/), [IP access rules](/waf/tools/ip-access-rules/)) | [Interstitial challenge page](#interstitial-challenge-pages) | +| [WAF](/waf/) ([custom rules](/waf/custom-rules/), [rate limiting rules](/waf/rate-limiting-rules/), [IP access rules](/waf/tools/ip-access-rules/)) | [Interstitial Challenge Page](/cloudflare-challenges/challenge-types/challenge-pages/) | | [Bot Management](/bots/get-started/bot-management/) | [JavaScript detection](/bots/additional-configurations/javascript-detections/) | -| [Bot Fight Mode](/bots/get-started/bot-fight-mode/), [Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/) | [Interstitial challenge page](#interstitial-challenge-pages) | +| [Bot Fight Mode](/bots/get-started/bot-fight-mode/), [Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/) | [Interstitial Challenge Page](/cloudflare-challenges/challenge-types/challenge-pages/) | | [Turnstile](/turnstile/) | Embedded widget | -| [HTTP DDoS attack protection](/ddos-protection/managed-rulesets/http/) | Any challenge | -| [Under Attack Mode](/fundamentals/reference/under-attack-mode/) | [Managed challenge](/cloudflare-challenges/challenge-types/challenge-pages/#managed-challenge-recommended) | +| [HTTP DDoS attack protection](/ddos-protection/managed-rulesets/http/) | Any Challenge | +| [Under Attack Mode](/fundamentals/reference/under-attack-mode/) | [Managed Challenge](/cloudflare-challenges/challenge-types/challenge-pages/#managed-challenge-recommended) | -### Turnstile +Challenge Pages and Turnstile rely on the same underlying mechanism to issue Challenges to your website or application's visitors. -[Turnstile](/turnstile/) is Cloudflare’s CAPTCHA-alternative solution. You can embed Turnstile as a widget on your site, where it runs a challenge directly in the visitor’s browser. +JavaScript detections support Cloudflare's Enterprise Bot Management. While it still relies on client-side detections, JavaScript detections function using a more performant challenge logic than Challenge Pages or Turnstile. -Turnstile does not pause the request or interrupt the user’s experience. Instead, the widget runs a client-side challenge in the background. In most cases, nothing further is required from the visitor. When needed, Turnstile may display a simple checkbox that the visitor must click to proceed. - -After the challenge passes, Turnstile issues a token that you must validate using the [siteverify API](/turnstile/get-started/server-side-validation/) before completing a sensitive action like login, sign up, or other form submissions. - -### Interstitial challenge pages - -When a challenge is triggered by a rule in the [Web Application Firewall (WAF)](/waf/), [Bot Management](/bots/), or [Rate Limiting](/waf/rate-limiting-rules/), Cloudflare presents a full-page interstitial challenge page. The request is paused while Cloudflare evaluates the browser environment. In some cases, the visitor may be asked to check a box for further probing. - -If the challenge passes, the original request continues to your origin. If the challenge fails or cannot be completed, the visitor is presented with another interstitial challenge page. - -### JavaScript detection in Bot Management - -In Bot Management, [JavaScript detections](/bots/additional-configurations/javascript-detections/) run silently in the browser to validate that the visitor supports and executes standard browser JavaScript, and provides a lightweight and privacy-preserving way to distinguish between bots and real users without adding friction to the experience. +--- -:::note -If the check fails, the bot score is set to 1. -::: +## Available Challenges -The script runs a short set of tasks and, if successful, sets a `cf_clearance` cookie indicating that the visitor passed the check. This is exposed as the `cf.bot_management.js_detection.passed` field that you can use in [WAF custom rules](/waf/custom-rules/) to take further action — such as issuing an interstitial challenge page. +Refer to the following pages for more information on the different challenge types: -If a visitor was unable to run JavaScript detection, the `cf.bot_management.js_detection.passed` field is set to `False`. Cloudflare advises that you should never block a request based on this field unless you are certain that the visitor has run JavaScript detections. +- [Interstitial Challenge Pages](/cloudflare-challenges/challenge-types/challenge-pages/) +- [Turnstile](/cloudflare-challenges/challenge-types/turnstile/) +- [JavaScript detections](/cloudflare-challenges/challenge-types/javascript-detections/) --- ## Limitations -Cloudflare challenges cannot support the following: +Cloudflare Challenges cannot support the following: - [Browser extensions](/cloudflare-challenges/reference/supported-browsers/#browser-extensions) that modify the browser's `User-Agent` value or Web APIs such as `Canvas` and `WebGL`. - Implementations where a domain serves a challenge page originally requested for another domain. -- Challenge pages cannot be embedded in cross-origin iframes. -- Client software where the solve request of a Managed Challenge comes from a different IP than the original IP a challenge request was issued to. For example, if you receive the challenge from one IP and solve it using another IP, the solve is not valid and you may encounter a challenge loop. \ No newline at end of file +- Challenge Pages cannot be embedded in cross-origin iframes. +- Client software where the solve request of a Managed Challenge comes from a different IP than the original IP a Challenge request was issued to. For example, if you receive the Challenge from one IP and solve it using another IP, the solve is not valid and you may encounter a Challenge loop. \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/concepts/index.mdx b/src/content/docs/cloudflare-challenges/concepts/index.mdx index ef49e3afbb9dcf5..99c6ec85d7cf66e 100644 --- a/src/content/docs/cloudflare-challenges/concepts/index.mdx +++ b/src/content/docs/cloudflare-challenges/concepts/index.mdx @@ -10,6 +10,6 @@ sidebar: import { DirectoryListing } from "~/components" -Refer to the following pages for more information on how challenges work: +Refer to the following pages for more information on how Challenges work: diff --git a/src/content/docs/cloudflare-challenges/troubleshooting/frequently-asked-questions.mdx b/src/content/docs/cloudflare-challenges/frequently-asked-questions.mdx similarity index 74% rename from src/content/docs/cloudflare-challenges/troubleshooting/frequently-asked-questions.mdx rename to src/content/docs/cloudflare-challenges/frequently-asked-questions.mdx index 834458680744633..e52d636556b4d14 100644 --- a/src/content/docs/cloudflare-challenges/troubleshooting/frequently-asked-questions.mdx +++ b/src/content/docs/cloudflare-challenges/frequently-asked-questions.mdx @@ -7,16 +7,16 @@ sidebar: ## Why am I being challenged on a Cloudflare-protected site? -Cloudflare issues challenges to website visitors to protect against malicious activity such as bot attacks and DDoS attacks. Key reasons include: +Cloudflare issues Challenges to website visitors to protect against malicious activity such as bot attacks and DDoS attacks. Key reasons include: -- **High threat score**: IP addresses with a high-risk score trigger challenges. +- **High threat score**: IP addresses with a high-risk score trigger Challenges. - **IP reputation**: If your IP has a history of suspicious activity, it may be flagged. - **Bot detection**: Automated traffic resembling bots is filtered by Cloudflare. - **Web Application Firewall (WAF) custom rules**: Site owners may set rules targeting specific regions or user agents. - **Browser Integrity Check**: Cloudflare verifies that browsers meet certain standards. -- **Challenge Passage**: Technologies like Privacy Pass reduce the frequency of repeated challenges. +- **Challenge Passage**: Technologies like Privacy Pass reduce the frequency of repeated Challenges. -To avoid repeated challenges, ensure your browser is up to date, disable any privacy tools that might block standard browser headers, or use a different network connection if your current one has a poor IP reputation. +To avoid repeated Challenges, ensure your browser is up to date, disable any privacy tools that might block standard browser headers, or use a different network connection if your current one has a poor IP reputation. ## How do I exclude certain requests from being blocked or challenged? @@ -25,7 +25,7 @@ In certain situations you want to enforce a blocking or challenging action but m Cloudflare supports two methods of allowing requests using WAF custom rules: - Exclude a type of request from being blocked or challenged in a custom rule by updating the rule expression, for example adding an exclusion based on IP address, ASN, or country. -- Create a separate custom rule with a [_Skip_ action](/waf/custom-rules/skip/). This skip rule must appear before the rule with the block/challenge action in the rules list. +- Create a separate custom rule with a [_Skip_ action](/waf/custom-rules/skip/). This skip rule must appear before the rule with the block or challenge action in the rules list. The examples below illustrate a few possible approaches. @@ -85,33 +85,33 @@ Block Amazon Web Services (AWS) and Google Cloud Platform (GCP) because of large Previously, unless you customize your front-end application, any AJAX request that is challenged will fail because AJAX calls are not rendered in the DOM. -Now, you can [opt-in to Turnstile’s Pre-Clearance cookies](/turnstile/concepts/pre-clearance-support/). This allows you to issue a challenge early in your web application flow and pre-clear users to interact with sensitive APIs. Clearance cookies issued by a Turnstile widget are automatically applied to the Cloudflare zone that the Turnstile widget is embedded on, with no configuration necessary. The duration of the clearance cookie’s validity is controlled by the zone-specific configurable [Challenge Passage](/cloudflare-challenges/challenge-types/challenge-pages/#challenge-passage) security setting. +Now, you can [opt-in to Turnstile's Pre-clearance cookies](/turnstile/concepts/pre-clearance-support/). This allows you to issue a Challenge early in your web application flow and pre-clear users to interact with sensitive APIs. Clearance cookies issued by a Turnstile widget are automatically applied to the Cloudflare zone that the Turnstile widget is embedded on, with no configuration necessary. The duration of the clearance cookie's validity is controlled by the zone-specific configurable [Challenge Passage](/cloudflare-challenges/challenge-types/challenge-pages/#challenge-passage) security setting. -## Why would I not find any failed challenges? +## Why would I not find any failed Challenges? -Users do not complete all challenges. Cloudflare issues challenges that are never answered — only 2-3% of all served challenges are usually answered. +Users do not complete all Challenges. Cloudflare issues Challenges that are never answered — only 2-3% of all served Challenges are usually answered. There are multiple reasons for this: -- Users give up on a challenge. -- Users try to solve a challenge but cannot provide an answer. -- Users keep refreshing the challenge, but never submit an answer. -- Cloudflare receives a malformed challenge answer. +- Users give up on a Challenge. +- Users try to solve a Challenge but cannot provide an answer. +- Users keep refreshing the Challenge, but never submit an answer. +- Cloudflare receives a malformed Challenge answer. -You can calculated the number of failed challenges as follows: `number of challenges issued - number of challenges solved`. +You can calculated the number of failed Challenges as follows: `number of Challenges issued - number of Challenges solved`. ## Why do I have matches for a firewall rule that was not supposed to match the request? Make sure you are looking at the correct request. -Only requests that triggered a challenge will match the request parameters of the rule. Subsequent requests with a `[js]challengeSolved` action may not match the parameters of the rule — for example, the bot score may have changed because the user solved a challenge. +Only requests that triggered a Challenge will match the request parameters of the rule. Subsequent requests with a `[js]challengeSolved` action may not match the parameters of the rule — for example, the bot score may have changed because the user solved a Challenge. -The "solved" action is an informative action about a previous request that matched a rule. This action states that "previously a rule had matched a request with the action set to _Interactive Challenge_ or _JS Challenge_ and now that challenge was answered." +The "solved" action is an informative action about a previous request that matched a rule. This action states that "previously a rule had matched a request with the action set to _Interactive Challenge_ or _JS Challenge_ and now that Challenge was answered." ## Are custom Content Security Policies (CSP) or custom error pages supported? -You cannot set your own Content Security Policy (CSP) and/or Referer-Policy via meta tags or [Transform Rules](/rules/transform/) in challenge pages. +You cannot set your own Content Security Policy (CSP) and/or Referer-Policy via meta tags or [Transform Rules](/rules/transform/) in Challenge Pages. -Origin headers also cannot be modified for challenge pages. +Origin headers also cannot be modified for Challenge Pages. -If you are setting any of these headers using Transform Rules for your entire website, you must prefix the rule with `not (starts_with(http.request.uri.path, "/cdn-cgi/challenge-platform/") or cf.response.error_type in {"managed_challenge" "iuam" "legacy_challenge" "country_challenge"})` in the rule expression to avoid issues with challenges. \ No newline at end of file +If you are setting any of these headers using Transform Rules for your entire website, you must prefix the rule with `not (starts_with(http.request.uri.path, "/cdn-cgi/challenge-platform/") or cf.response.error_type in {"managed_challenge" "iuam" "legacy_challenge" "country_challenge"})` in the rule expression to avoid issues with Challenges. \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/index.mdx b/src/content/docs/cloudflare-challenges/index.mdx index 2e1beee14ec03a1..b8914c37799c75f 100644 --- a/src/content/docs/cloudflare-challenges/index.mdx +++ b/src/content/docs/cloudflare-challenges/index.mdx @@ -11,7 +11,9 @@ import { Render, Description, Plan, RelatedProduct } from "~/components"; Challenges are security mechanisms used by Cloudflare to verify whether a visitor to your site is a real human and not a bot or automated script. -When a challenge is issued, Cloudflare asks the browser to perform a series of checks that help confirm the visitor’s legitimacy. This process involves evaluating client side signals or asking a visitor to take minimal action such as checking a box. Challenges are designed to protect your application without introducing unnecessary friction. Most visitors will pass challenges automatically without interaction. +When a Challenge is issued, Cloudflare asks the browser to perform a series of checks that help confirm the visitor's legitimacy. This process involves evaluating client-side signals or asking a visitor to take minimal action such as checking a box or selecting a button. + +Challenges are designed to protect your application without introducing unnecessary friction. Most visitors will pass Challenges automatically without interaction. Cloudflare does not use CAPTCHA puzzles or visual tests like selecting objects or typing distorted characters. All challenge types are lightweight, privacy-preserving, and optimized for real-world traffic. @@ -20,7 +22,7 @@ Cloudflare does not use CAPTCHA puzzles or visual tests like selecting objects o ## Related products - Use Cloudflare's smart CAPTCHA alternative to run less intrusive challenges. + Use Cloudflare's smart CAPTCHA alternative to run less intrusive Challenges. diff --git a/src/content/docs/cloudflare-challenges/reference/index.mdx b/src/content/docs/cloudflare-challenges/reference/index.mdx index defab8645f40101..4ed27cf2217939c 100644 --- a/src/content/docs/cloudflare-challenges/reference/index.mdx +++ b/src/content/docs/cloudflare-challenges/reference/index.mdx @@ -9,6 +9,6 @@ sidebar: import { DirectoryListing } from "~/components" -Refer to the following pages for more information about Cloudflare challenges: +Refer to the following pages for more information about Cloudflare Challenges: \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/reference/private-access-tokens.mdx b/src/content/docs/cloudflare-challenges/reference/private-access-tokens.mdx index 70322a5d4219c56..8c2e4b93190fab3 100644 --- a/src/content/docs/cloudflare-challenges/reference/private-access-tokens.mdx +++ b/src/content/docs/cloudflare-challenges/reference/private-access-tokens.mdx @@ -5,8 +5,8 @@ sidebar: order: 3 --- -When a user is presented with a challenge page, Cloudflare decides what challenges need to be solved to prove they are human using results from the Private Access Token (PAT). If a user presents a token, they will have an easier time solving the challenge. +When a user is presented with a Challenge Page, Cloudflare decides what Challenges need to be solved to prove they are human using results from the Private Access Token (PAT). If a user presents a token, they will have an easier time solving the Challenge. -While some challenges are computationally complex or require interactivity, most of the challenges served are invisible to the user. +While some Challenges are computationally complex or require interactivity, most of the Challenges served are invisible to the user. -The challenge page is an interstitial page and users will see it regardless of having a valid PAT or not. A PAT does not automatically solve a challenge. It prevents certain challenges from being issued. \ No newline at end of file +The Challenge Page is an interstitial page and users will encounter it regardless of having a valid PAT or not. A PAT does not automatically solve a Challenge. It prevents certain Challenges from being issued. \ No newline at end of file diff --git a/src/content/docs/cloudflare-challenges/reference/supported-browsers.mdx b/src/content/docs/cloudflare-challenges/reference/supported-browsers.mdx index 206f88b9254ecd9..2dcc751ca3d1fe4 100644 --- a/src/content/docs/cloudflare-challenges/reference/supported-browsers.mdx +++ b/src/content/docs/cloudflare-challenges/reference/supported-browsers.mdx @@ -7,13 +7,13 @@ sidebar: import { Details } from "~/components" -Cloudflare can challenge your visitors in various ways. They can be challenged by [Challenge Pages](/cloudflare-challenges/challenge-types/challenge-pages/), [Turnstile](/turnstile/), or by [JavaScript Detections (JSD) in Bot Management](/cloudflare-challenges/challenge-types/javascript-detections/). This document lays out the supported browsers across all of these challenge methods. When your website or application presents a challenge, your visitors receive either a non-interactive or an interactive challenge. +Cloudflare can challenge your visitors in various ways. They can be challenged by [Challenge Pages](/cloudflare-challenges/challenge-types/challenge-pages/), [Turnstile](/turnstile/), or by [JavaScript Detections (JSD) in Bot Management](/cloudflare-challenges/challenge-types/javascript-detections/). This document lays out the supported browsers across all of these challenge methods. When your website or application presents a Challenge, your visitors receive either a Non-interactive or an Interactive Challenge. -Cloudflare is committed to ensuring our challenges work with as many browsers as possible, but there are limitations that you should be aware of. +Cloudflare is committed to ensuring our Challenges work with as many browsers as possible, but there are limitations that you should be aware of. ## Overview -Cloudflare challenges are designed to be compatible with any desktop and mobile browser. If your visitors are using an up-to-date version of a browser listed below, they will receive and be able to solve challenges without any issues. The following is a non-exclusive list of browsers supported by Cloudflare challenges. Browsers not listed on this list are supported on a best-effort basis. +Cloudflare Challenges are designed to be compatible with any desktop and mobile browser. If your visitors are using an up-to-date version of a browser listed below, they will receive and be able to solve Challenges without any issues. The following is a non-exclusive list of browsers supported by Cloudflare Challenges. Browsers not listed on this list are supported on a best-effort basis. ### Supported browsers @@ -62,23 +62,23 @@ If your visitors encounter issues using these browsers, we recommend upgrading t The following environments are not supported. -- Command-line tools such as `wget`, `curl`, or others that lack JavaScript execution capabilities required for Cloudflare challenges. +- Command-line tools such as `wget`, `curl`, or others that lack JavaScript execution capabilities required for Cloudflare Challenges. - Headless browsers like headless Chrome, headless Firefox, PhantomJS, or others. Challenges are specifically designed to identify and block headless browser traffic. Automation tools and scripts that use headless browsers are not supported. -- Browser automation frameworks such as Selenium, Puppeteer, Playwright, or others that are considered automated traffic will be blocked by challenges. +- Browser automation frameworks such as Selenium, Puppeteer, Playwright, or others that are considered automated traffic will be blocked by Challenges. ## Common issues ### Browser extensions -Browser extensions can interfere with challenges in several ways. +Browser extensions can interfere with Challenges in several ways. -- Ad blockers and content blockers may prevent challenge scripts from loading properly or block communication with Cloudflare's validation servers. -- Privacy-focused extensions like script blockers, fingerprinting protection, or canvas blockers can interfere with the challenge verification process. +- Ad blockers and content blockers may prevent Challenge scripts from loading properly or block communication with Cloudflare's validation servers. +- Privacy-focused extensions like script blockers, fingerprinting protection, or canvas blockers can interfere with the Challenge verification process. - VPN or proxy extensions might trigger additional security checks or cause IP address inconsistencies. -- Browser automation tools are often detected as potential bots and may cause challenge failures. +- Browser automation tools are often detected as potential bots and may cause Challenge failures. :::note -If challenges consistently fail, try temporarily disabling extensions and reload the page. +If Challenges consistently fail, try temporarily disabling extensions and reload the page. ::: ### Device emulation and developer tools @@ -86,13 +86,13 @@ If challenges consistently fail, try temporarily disabling extensions and reload Challenges are designed to distinguish between real human users and automated traffic. When device emulation is enabled (such as through browser developer tools), it can trigger bot detection mechanisms. - Mobile device emulation in desktop browsers often uses distinctive characteristics that differ from real mobile devices. -- Developer tools may modify browser behavior or expose debugging information that changes how challenges operate. +- Developer tools may modify browser behavior or expose debugging information that changes how Challenges operate. - Automation frameworks like Selenium, Puppeteer, or Playwright are specifically detected as non-human traffic. :::note For developers testing applications, we recommend using real devices rather than emulated environments when possible. -If you must use emulation, be aware that challenges may be more difficult to pass, and do not reflect the real experience on mobile devices. +If you must use emulation, be aware that Challenges may be more difficult to pass, and do not reflect the real experience on mobile devices. ::: ### WebViews and in-app browsers @@ -101,8 +101,8 @@ Challenges may behave differently depending on embedded browser contexts. - WebViews in mobile applications may have limited functionality compared to full browsers - In-app browsers often have restricted JavaScript capabilities -- Email client preview windows typically cannot complete interactive challenges +- Email client preview windows typically cannot complete Interactive Challenges ## Troubleshooting -If your visitors consistently experience challenge issues, refer to [Challenge solve issues](/cloudflare-challenges/troubleshooting/challenge-solve-issues/) for additional troubleshooting information. +If your visitors consistently experience Challenge issues, refer to [Challenge solve issues](/cloudflare-challenges/troubleshooting/challenge-solve-issues/) for additional troubleshooting information. diff --git a/src/content/docs/cloudflare-challenges/reference/supported-languages.mdx b/src/content/docs/cloudflare-challenges/reference/supported-languages.mdx index 89a110c2a0f71d3..42575c9eb7b4c8f 100644 --- a/src/content/docs/cloudflare-challenges/reference/supported-languages.mdx +++ b/src/content/docs/cloudflare-challenges/reference/supported-languages.mdx @@ -7,9 +7,9 @@ sidebar: ## Multi-language support -Cloudflare's challenges can detect multiple languages and display the localized challenge experience, which is determined by `navigator.language` value. The [Navigator.language read-only property](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) returns a string representing the preferred language of the user, usually the language of the browser user interface. +Cloudflare Challenges can detect multiple languages and display the localized Challenge experience, which is determined by `navigator.language` value. The [Navigator.language read-only property](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) returns a string representing the preferred language of the user, usually the language of the browser user interface. -For language support specific to challenge pages, refer to the table below. +For language support specific to Challenge Pages, refer to the table below. | Language | Language code
(4 letters) | Language code
(2 letters) | | -------------------------------- | ----------------------------- | ----------------------------- | diff --git a/src/content/docs/cloudflare-challenges/troubleshooting/challenge-solve-issues.mdx b/src/content/docs/cloudflare-challenges/troubleshooting/challenge-solve-issues.mdx index e3f6a40f18dc373..5229287eeae89f2 100644 --- a/src/content/docs/cloudflare-challenges/troubleshooting/challenge-solve-issues.mdx +++ b/src/content/docs/cloudflare-challenges/troubleshooting/challenge-solve-issues.mdx @@ -10,15 +10,15 @@ import { Render } from "~/components" ## Challenge loops -You may encounter a challenge loop where the challenge keeps reappearing without being solved. This is in very specific cases where we detect strong bot signals. If you are a legitimate human, you can follow the troubleshooting guide below to resolve the issue or submit a feedback report. Challenge loops can happen for several reasons: +You may encounter a Challenge loop where the Challenge keeps reappearing without being solved. This is in very specific cases where we detect strong bot signals. If you are a legitimate human, you can follow the troubleshooting guide below to resolve the issue or submit a feedback report. Challenge loops can happen for several reasons: -- **Network issues**: Poor or unstable network connections can prevent the challenge from being completed. -- **Browser configuration**: Some browser settings or extensions may block the scripts needed to execute the challenge. +- **Network issues**: Poor or unstable network connections can prevent the Challenge from being completed. +- **Browser configuration**: Some browser settings or extensions may block the scripts needed to execute the Challenge. - **Unsupported browsers**: Using a browser that is not supported by Turnstile. - **JavaScript disabled**: Turnstile relies on JavaScript to function properly. -- **Detection errors**: If Turnstile suspects bot-like behavior, you may encounter repeated challenges for verification. +- **Detection errors**: If Turnstile suspects bot-like behavior, you may encounter repeated Challenges for verification. -Most challenges are quick to complete and typically take only a few seconds. If it takes longer, ensure your network is stable and follow the [troubleshooting steps](#troubleshooting). +Most Challenges are quick to complete and typically take only a few seconds. If it takes longer, ensure your network is stable and follow the [troubleshooting steps](#troubleshooting). :::note If the issue persists, try switching to a different network or device to rule out any issues with your browser environment. diff --git a/src/content/docs/cloudflare-challenges/troubleshooting/index.mdx b/src/content/docs/cloudflare-challenges/troubleshooting/index.mdx index 0cbac9c0ab83d97..e9ffa46084fa3f7 100644 --- a/src/content/docs/cloudflare-challenges/troubleshooting/index.mdx +++ b/src/content/docs/cloudflare-challenges/troubleshooting/index.mdx @@ -21,10 +21,10 @@ Challenges are not supported by Microsoft Internet Explorer. If you are currentl ### Referer header -When a request is sent with a referer header, the user will receive a challenge page as a response. Upon solving the challenge page, the request with the referer is sent to the origin, and the response to the request is served to the user. The JavaScript on the response page may read the value of `document.referer`, but it will be inaccurate. This affects tools such as Google Analytics, which reads the referer from JavaScript. +When a request is sent with a referer header, the user will receive a Challenge Page as a response. Upon solving the Challenge Page, the request with the referer is sent to the origin, and the response to the request is served to the user. The JavaScript on the response page may read the value of `document.referer`, but it will be inaccurate. This affects tools such as Google Analytics, which reads the referer from JavaScript. -You can add tracking scripts to challenge pages to capture the correct referer header on the initial request. +You can add tracking scripts to Challenge Pages to capture the correct referer header on the initial request. ### Cross-origin resource sharing (CORS) preflight requests -Cross-origin resource sharing (CORS) preflight requests, or `OPTIONS`, exclude user credentials that include cookies. As a result, the `cf_clearance` cookie will not be sent with the request, causing it to fail to bypass a challenge page (non-interactive, managed, or interactive challenge). \ No newline at end of file +Cross-origin resource sharing (CORS) preflight requests, or `OPTIONS`, exclude user credentials that include cookies. As a result, the `cf_clearance` cookie will not be sent with the request, causing it to fail to bypass a Challenge Page (Non-interactive, Managed, or Interactive Challenge). \ No newline at end of file diff --git a/src/content/docs/pages/functions/plugins/turnstile.mdx b/src/content/docs/pages/functions/plugins/turnstile.mdx index 83e7727ee9728e6..e1b990bb5bf2213 100644 --- a/src/content/docs/pages/functions/plugins/turnstile.mdx +++ b/src/content/docs/pages/functions/plugins/turnstile.mdx @@ -62,4 +62,4 @@ The Plugin is mounted with a single object parameter with the following properti `onError` is an optional function which takes the Pages Function context object and returns a `Promise` of a `Response`. By default, it will return a human-readable error `Response`. -`context.data.turnstile` will be populated in subsequent Pages Functions (including for the `onError` function) with [the Turnstile siteverify response object](/turnstile/get-started/server-side-validation/). +`context.data.turnstile` will be populated in subsequent Pages Functions (including for the `onError` function) with [the Turnstile Siteverify response object](/turnstile/get-started/server-side-validation/). diff --git a/src/content/docs/turnstile/concepts/hostname-management.mdx b/src/content/docs/turnstile/concepts/hostname-management.mdx index 7e5b30f4a0848a2..a9d2f8d0445499f 100644 --- a/src/content/docs/turnstile/concepts/hostname-management.mdx +++ b/src/content/docs/turnstile/concepts/hostname-management.mdx @@ -36,7 +36,7 @@ If you already have a zone registered with Cloudflare, you can add hostnames dur ## Hostname requirements :::caution -Customers enabling [client-side rendering](/turnstile/get-started/client-side-rendering/) must validate their hostnames by looking at the [`hostname`](/turnstile/get-started/server-side-validation/#:~:text=challenge%20was%20solved.-,hostname,-is%20the%20hostname) field in the siteverify response. +Customers enabling [client-side rendering](/turnstile/get-started/client-side-rendering/) must validate their hostnames by looking at the [`hostname`](/turnstile/get-started/server-side-validation/#:~:text=challenge%20was%20solved.-,hostname,-is%20the%20hostname) field in the Siteverify response. ::: When associating hostnames with a widget, follow these requirements: diff --git a/src/content/docs/turnstile/concepts/pre-clearance-support.mdx b/src/content/docs/turnstile/concepts/pre-clearance-support.mdx index 2eb3642df073f68..286bdbeb4f4fe95 100644 --- a/src/content/docs/turnstile/concepts/pre-clearance-support.mdx +++ b/src/content/docs/turnstile/concepts/pre-clearance-support.mdx @@ -1,41 +1,8 @@ --- title: Pre-clearance support pcx_content_type: reference +external_link: /cloudflare-challenges/concepts/clearance/#pre-clearance-support-in-turnstile sidebar: order: 3 ---- - -Pre-clearance in Turnstile allows websites to streamline user experiences by using clearance cookies. These cookies enable visitors to bypass WAF challenges downstream, based on the security clearance level set by the customer. This can be particularly useful for trusted visitors, enhancing usability while maintaining security. - -You can integrate Cloudflare challenges by allowing Turnstile to issue a pre-clearance cookie. The pre-clearance level is set upon widget creation or widget modification using the Turnstile API's `clearance_level`. Possible values for the configuration are: - -- `no_clearance` -- `jschallenge` -- `managed` -- `interactive` - -All widgets are set to `no_clearance` by default. - -For Enterprise customers eligible to toggle off domain checks, Cloudflare recommends issuing pre-clearance cookies on widgets where at least one domain is specified. - -:::note - -Clearance cookies only support zones that are orange-clouded. -::: - -Refer to the [blog post](https://blog.cloudflare.com/integrating-turnstile-with-the-cloudflare-waf-to-challenge-fetch-requests) for more details on how pre-clearance works with WAF. - -## Pre-clearance level options - -- **Interactive (High)**: Allows a user with a clearance cookie to not be challenged by Interactive, Managed Challenge, or JavaScript Challenge Firewall Rules -- **Managed (Medium)**: Allows a user with a clearance cookie to not be challenged by Managed Challenge or JavaScript Challenge Firewall Rules -- **Non-interactive (Low)**: Allows a user with a clearance cookie to not be challenged by JavaScript Challenge Firewall Rules - -## Clearance cookie duration - -Clearance cookies generated by the Turnstile widget will be valid for the time specified by the zone-level Challenge Passage value. To configure the Challenge Passage setting, refer to the [Challenges documentation](/cloudflare-challenges/challenge-types/challenge-pages/#challenge-passage). - -## Setup - -To set up pre-clearance cookies, refer to [Enable pre-clearance cookies](/turnstile/get-started/pre-clearance/). \ No newline at end of file +--- \ No newline at end of file diff --git a/src/content/docs/turnstile/get-started/client-side-rendering.mdx b/src/content/docs/turnstile/get-started/client-side-rendering.mdx index 624d1a2bdd1b39f..46faafa12fa0b91 100644 --- a/src/content/docs/turnstile/get-started/client-side-rendering.mdx +++ b/src/content/docs/turnstile/get-started/client-side-rendering.mdx @@ -35,7 +35,7 @@ The HTML is scanned for elements that have a `cf-turnstile` class name:
-Once a challenge has been solved, a token is passed to the success callback. This token must be validated against our siteverify endpoint. A token can only be validated once and cannot be consumed twice. +Once a challenge has been solved, a token is passed to the success callback. This token must be validated against the Siteverify API. A token can only be validated once and cannot be consumed twice. @@ -67,7 +67,7 @@ An invisible input with the name `cf-turnstile-response` is added and will be se :::note -A form is not protected by having a widget rendered. The corresponding token that is a result of a widget being rendered also needs to be verified using the siteverify API. +A form is not protected by having a widget rendered. The corresponding token that is a result of a widget being rendered also needs to be verified using the Siteverify API. ::: ### Disable implicit rendering diff --git a/src/content/docs/turnstile/get-started/mobile-implementation.mdx b/src/content/docs/turnstile/get-started/mobile-implementation.mdx index 7c845f17b479087..9da942a50d7633c 100644 --- a/src/content/docs/turnstile/get-started/mobile-implementation.mdx +++ b/src/content/docs/turnstile/get-started/mobile-implementation.mdx @@ -8,7 +8,7 @@ sidebar: Turnstile is designed to run in a standard browser environment, which includes mobile devices. On native mobile applications, Turnstile can be used with WebViews. This applies to native web applications for iOS and Android. When implementing Turnstile for mobile, ensure you address the common issues below to avoid integration problems. -Any modifications to the environment, such as the User Agent, [Content Security Policy settings](/turnstile/reference/content-security-policy/), or domain allowlisting, can disrupt the successful completion of Turnstile challenges. To ensure compatibility, it is recommended to start with a default, unmodified environment and gradually introduce changes, validating Turnstile’s functionality after each adjustment. +Any modifications to the environment, such as the User Agent, [Content Security Policy settings](/turnstile/reference/content-security-policy/), or domain allowlisting, can disrupt the successful completion of Turnstile challenges. To ensure compatibility, it is recommended to start with a default, unmodified environment and gradually introduce changes, validating Turnstile's functionality after each adjustment. ## WebView configurations @@ -46,4 +46,4 @@ If pre-clearance is done in a different environment, the clearance cookie may be ## Use Flutter with Turnstile -For developers using [Flutter](https://pub.dev/packages/flutter_inappwebview), Turnstile is compatible and tested with Flutter’s WebView implementation. Refer to the official Flutter WebView package for more details and usage. \ No newline at end of file +For developers using [Flutter](https://pub.dev/packages/flutter_inappwebview), Turnstile is compatible and tested with Flutter's WebView implementation. Refer to the official Flutter WebView package for more details and usage. \ No newline at end of file diff --git a/src/content/docs/turnstile/get-started/server-side-validation.mdx b/src/content/docs/turnstile/get-started/server-side-validation.mdx index caf1e6c41d434ce..34082e3f3837cae 100644 --- a/src/content/docs/turnstile/get-started/server-side-validation.mdx +++ b/src/content/docs/turnstile/get-started/server-side-validation.mdx @@ -9,20 +9,20 @@ import { GlossaryTooltip, Render, TabItem, Tabs } from "~/components"; -Turnstile needs to be verified using siteverify because it is a front-end widget that creates a token which is cryptographically secured. To ensure that a token is not forged by an attacker or has not been consumed yet, it is necessary to check the validity of a token using Cloudflare's siteverify API. +Turnstile needs to be verified using Siteverify because it is a front-end widget that creates a token which is cryptographically secured. To ensure that a token is not forged by an attacker or has not been consumed yet, it is necessary to check the validity of a token using Cloudflare's Siteverify API. -You must call the siteverify endpoint to validate the Turnstile widget response from your website’s backend. The widget response must only be considered valid once it has been verified by the siteverify endpoint. The presence of a response alone is not enough to verify it as it does not protect from replay or forgery attacks. In some cases, Turnstile may purposely create invalid responses that are rejected by the siteverify API. +You must call the Siteverify endpoint to validate the Turnstile widget response from your website's backend. The widget response must only be considered valid once it has been verified by the Siteverify endpoint. The presence of a response alone is not enough to verify it as it does not protect from replay or forgery attacks. In some cases, Turnstile may purposely create invalid responses that are rejected by the Siteverify API. -Tokens issued to Turnstile using the success callbacks, via explicit or implicit rendering, must be validated using the siteverify endpoint. The siteverify API will only validate a token once. If a token has already been checked, the siteverify API will yield an error on subsequent verification attempts indicating that a token has already been consumed. +Tokens issued to Turnstile using the success callbacks, via explicit or implicit rendering, must be validated using the Siteverify endpoint. The Siteverify API will only validate a token once. If a token has already been checked, the Siteverify API will yield an error on subsequent verification attempts indicating that a token has already been consumed. :::note A Turnstile token can have up to 2048 characters. -It is also valid for 300 seconds before it is rejected by siteverify. +It is also valid for 300 seconds before it is rejected by Siteverify. ::: -The siteverify endpoint needs to be passed a secret key that is associated with the sitekey. The secret key will be provisioned alongside the sitekey when you create a widget. Furthermore, the response needs to be passed to the siteverify endpoint. +The Siteverify endpoint needs to be passed a secret key that is associated with the sitekey. The secret key will be provisioned alongside the sitekey when you create a widget. Furthermore, the response needs to be passed to the Siteverify endpoint. A response may only be validated once. If the same response is presented twice, the second and each subsequent request will generate an error stating that the response has already been consumed. If an application requires to retry failed requests, it must utilize the idempotency functionality. You can do so by providing a UUID as the `idempotency_key` parameter of your `POST` request when initially validating the response and the same UUID with any subsequent request for that response. @@ -244,7 +244,7 @@ async function handlePost(request) { The `remoteip` parameter helps to prevent abuse by ensuring the current visitor is the one who received the token. This is currently not strictly validated. ::: -The siteverify endpoint behaves similar to reCAPTCHA’s or hCaptcha's siteverify endpoint. +The Siteverify endpoint behaves similar to reCAPTCHA's or hCaptcha's Siteverify endpoint. The API accepts `application/x-www-form-urlencoded` and `application/json` requests, but the response type will always be `application/json`. It always contains a `success` property, either true or false, indicating whether the operation was successful or not. @@ -272,7 +272,7 @@ It always contains a `success` property, either true or false, indicating whethe - `action` is the customer widget identifier passed to the widget on the client side. This is used to differentiate widgets using the same sitekey in analytics. Its integrity is protected by modifications from an attacker. It is recommended to validate that the action matches an expected value. - `cdata` is the customer data passed to the widget on the client side. This can be used by the customer to convey state. It is integrity protected by modifications from an attacker. - `error-codes` is a list of errors that occurred. -- (Enterprise only) `ephemeral_id` returns the [Ephemeral ID](/turnstile/concepts/ephemeral-id/) in siteverify. +- (Enterprise only) `ephemeral_id` returns the [Ephemeral ID](/turnstile/concepts/ephemeral-id/) in Siteverify. In case of a validation failure, the response should be similar to the following: @@ -287,7 +287,7 @@ In case of a validation failure, the response should be similar to the following
-A validation error is indicated by having the `success` property set to `false`. A list of error codes is provided to indicate why a response has failed to verify. The response may also contain additional fields based on whether Turnstile siteverify was able to parse the response successfully or unsuccessfully. +A validation error is indicated by having the `success` property set to `false`. A list of error codes is provided to indicate why a response has failed to verify. The response may also contain additional fields based on whether Turnstile Siteverify was able to parse the response successfully or unsuccessfully. ## Error codes diff --git a/src/content/docs/turnstile/index.mdx b/src/content/docs/turnstile/index.mdx index d07cdb4bde3808e..973317d6e104937 100644 --- a/src/content/docs/turnstile/index.mdx +++ b/src/content/docs/turnstile/index.mdx @@ -20,7 +20,7 @@ import { -Cloudflare’s smart CAPTCHA alternative. +Cloudflare's smart CAPTCHA alternative. diff --git a/src/content/docs/turnstile/migration/hcaptcha.mdx b/src/content/docs/turnstile/migration/hcaptcha.mdx index a4048c325e56e47..4a406ed880d3967 100644 --- a/src/content/docs/turnstile/migration/hcaptcha.mdx +++ b/src/content/docs/turnstile/migration/hcaptcha.mdx @@ -49,5 +49,5 @@ Turnstile supports: ## Server-side integration -1. Update the server-side integration by replacing the siteverify URL. Replace: `https://hcaptcha.com/siteverify` with `https://challenges.cloudflare.com/turnstile/v0/siteverify`. +1. Update the server-side integration by replacing the Siteverify URL. Replace: `https://hcaptcha.com/siteverify` with `https://challenges.cloudflare.com/turnstile/v0/siteverify`. 2. Replace the `h-captcha-response` input name with `cf-turnstile-response`. diff --git a/src/content/docs/turnstile/migration/recaptcha.mdx b/src/content/docs/turnstile/migration/recaptcha.mdx index a1f9e0c0e8c21a2..736e3891720d9e6 100644 --- a/src/content/docs/turnstile/migration/recaptcha.mdx +++ b/src/content/docs/turnstile/migration/recaptcha.mdx @@ -49,13 +49,13 @@ Turnstile supports: ## Server-side integration -Update the server-side integration by replacing the siteverify URL. Replace `https://www.google.com/recaptcha/api/siteverify` with `https://challenges.cloudflare.com/turnstile/v0/siteverify` +Update the server-side integration by replacing the Siteverify URL. Replace `https://www.google.com/recaptcha/api/siteverify` with `https://challenges.cloudflare.com/turnstile/v0/siteverify` -:::caution[Differences to reCAPTCHA's siteverify] +:::caution[Differences to reCAPTCHA's Siteverify] reCAPTCHA supports `GET` requests using query parameters, i.e: `GET /siteverify?response=&secret=`. -Turnstile's siteverify endpoint does _not_ support this and only accepts `POST` requests with a FormData or JSON body. +Turnstile's Siteverify endpoint does _not_ support this and only accepts `POST` requests with a FormData or JSON body. Refer to [server-side validation](/turnstile/get-started/server-side-validation/) for more information. ::: diff --git a/src/content/docs/turnstile/reference/workers-templates/price-scraping.mdx b/src/content/docs/turnstile/reference/workers-templates/price-scraping.mdx index 9938fec2a36aa97..210aa4a7a603aa7 100644 --- a/src/content/docs/turnstile/reference/workers-templates/price-scraping.mdx +++ b/src/content/docs/turnstile/reference/workers-templates/price-scraping.mdx @@ -73,7 +73,7 @@ async function getPrice(token){ ); // await price information from pricing endpoint const price = await response.json(); - // set the pricing information to what’s returned in the callback + // set the pricing information to what's returned in the callback priceBox.innerText = price.pricing } function init(){ diff --git a/src/content/docs/turnstile/troubleshooting/client-side-errors/error-codes.mdx b/src/content/docs/turnstile/troubleshooting/client-side-errors/error-codes.mdx index 12a98c7cdb8d94a..1898b69992dfeae 100644 --- a/src/content/docs/turnstile/troubleshooting/client-side-errors/error-codes.mdx +++ b/src/content/docs/turnstile/troubleshooting/client-side-errors/error-codes.mdx @@ -18,7 +18,7 @@ When an error code is marked with `***`, it means that the remaining numbers can | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `100***` | Initialization Problems: There was a problem initializing Turnstile before a challenge could be started. | No | This could be caused by an old instance of the challenge that was solved. It is advised to reload the page and restart Turnstile. On continuous failures, this is indicative of an automated device. | | `102***` | Invalid Parameters: The visitor sent an invalid parameter as part of the challenge towards Turnstile. | Yes | It is advised to retry the challenge. On continuous failures, this is indicative of an automated device. | -| `102***`
`103***`
`104***`
`106***` | Invalid Parameters: The visitor sent an invalid parameter as part of the challenge towards Turnstile. | Yes | It is advised to retry the challenge. On continuous failures, this is indicative of an automated device and you must verify the visitor’s authenticity by other means. | +| `102***`
`103***`
`104***`
`106***` | Invalid Parameters: The visitor sent an invalid parameter as part of the challenge towards Turnstile. | Yes | It is advised to retry the challenge. On continuous failures, this is indicative of an automated device and you must verify the visitor's authenticity by other means. | | `105***` | Turnstile API Compatibility: Turnstile was invoked in a deprecated or invalid way. | No | It is advised to refer to the [Turnstile documentation](/turnstile/) again and refresh the page to obtain the most recent Turnstile version. | | `110100`
`110110` | Invalid sitekey: Turnstile was invoked with an invalid sitekey or a sitekey that is no longer active. | No | Verify if the sitekey provided is still active via the [Cloudflare dashboard](https://dash.cloudflare.com/). | | `110200` | Unknown domain: Domain not allowed. | No | Turnstile was used on a domain that was not allowed for this widget to be used on. Ensure that the domain is allowed in the widget configuration via the [Cloudflare dashboard](https://dash.cloudflare.com/). | diff --git a/src/content/docs/turnstile/troubleshooting/troubleshooting-faqs.mdx b/src/content/docs/turnstile/troubleshooting/troubleshooting-faqs.mdx index d1764f6f6c6d6ac..6286d68b7a4754d 100644 --- a/src/content/docs/turnstile/troubleshooting/troubleshooting-faqs.mdx +++ b/src/content/docs/turnstile/troubleshooting/troubleshooting-faqs.mdx @@ -12,9 +12,9 @@ import { Render } from "~/components" The Turnstile widget needs to be refreshed to generate a new token. This can be done using the `turnstile.reset` function. -## Can the front end use siteverify? +## Can the front end use Siteverify? -The siteverify API must not be called by the front end as this may reveal the secret key used to authenticate. An attacker may simply modify the front end to not perform the siteverify check at all, rendering Turnstile ineffective. +The Siteverify API must not be called by the front end as this may reveal the secret key used to authenticate. An attacker may simply modify the front end to not perform the siteverify check at all, rendering Turnstile ineffective. ## What is challenges.cloudflare.com, and why does my application connect to this origin? diff --git a/src/content/docs/turnstile/turnstile-analytics/challenge-outcomes.mdx b/src/content/docs/turnstile/turnstile-analytics/challenge-outcomes.mdx index aed3e9c224277dd..8bd4164c49d0407 100644 --- a/src/content/docs/turnstile/turnstile-analytics/challenge-outcomes.mdx +++ b/src/content/docs/turnstile/turnstile-analytics/challenge-outcomes.mdx @@ -11,7 +11,7 @@ When a visitor encounters Turnstile, it assesses whether they are human or bot-l ## Metrics -A "solved" Turnstile challenge does not automatically confirm the visitor is human. You must [call the siteverify API](#call-siteverify) to validate the token and proceed only if the response returns `success:true`. +A "solved" Turnstile challenge does not automatically confirm the visitor is human. You must [call the Siteverify API](#call-siteverify) to validate the token and proceed only if the response returns `success:true`. For example, the challenge outcome values in your analytics may look like this: @@ -25,7 +25,7 @@ For example, the challenge outcome values in your analytics may look like this: By analyzing these metrics, you can identify trends such as high failure rates in specific regions, device types, or traffic sources, which may indicate bot activity or misconfigurations. -### Call siteverify +### Call Siteverify diff --git a/src/content/docs/turnstile/turnstile-analytics/token-validation.mdx b/src/content/docs/turnstile/turnstile-analytics/token-validation.mdx index 6298bafa947a8fb..22c8d7ecbf98765 100644 --- a/src/content/docs/turnstile/turnstile-analytics/token-validation.mdx +++ b/src/content/docs/turnstile/turnstile-analytics/token-validation.mdx @@ -7,7 +7,7 @@ sidebar: import { Render } from "~/components" -After a visitor successfully completes a Turnstile challenge, a token is generated and validated via the siteverify API. Token validation data provides crucial insights into your security posture. +After a visitor successfully completes a Turnstile challenge, a token is generated and validated via the Siteverify API. Token validation data provides crucial insights into your security posture. For example, the token validation values in your analytics may look like this: @@ -15,10 +15,10 @@ For example, the token validation values in your analytics may look like this: ## Metrics -- **Siteverify requests**: The total number of requests made to the siteverify API in the given timeframe. -- **Valid tokens**: The number of siteverify requests with `success:true` responses. -- **Invalid tokens**: The number of siteverify requests with `success:false` responses. +- **Siteverify requests**: The total number of requests made to the Siteverify API in the given timeframe. +- **Valid tokens**: The number of Siteverify requests with `success:true` responses. +- **Invalid tokens**: The number of Siteverify requests with `success:false` responses. -### Call siteverify +### Call Siteverify \ No newline at end of file diff --git a/src/content/docs/turnstile/tutorials/conditionally-enforcing-turnstile.mdx b/src/content/docs/turnstile/tutorials/conditionally-enforcing-turnstile.mdx index 7b25ab214d9d073..f368306e2446205 100644 --- a/src/content/docs/turnstile/tutorials/conditionally-enforcing-turnstile.mdx +++ b/src/content/docs/turnstile/tutorials/conditionally-enforcing-turnstile.mdx @@ -15,14 +15,14 @@ This tutorial explains how to conditionally enforce Turnstile based on the incom ## Overview -You may have setups such as automation that cannot load or run the Turnstile challenge. Using [`HTMLRewriter`](/workers/runtime-apis/html-rewriter/), this tutorial will demonstrate how to conditionally handle the [client-side widget](/turnstile/get-started/client-side-rendering/) and [siteverify API](/turnstile/get-started/server-side-validation/) when specific criteria are met. +You may have setups such as automation that cannot load or run the Turnstile challenge. Using [`HTMLRewriter`](/workers/runtime-apis/html-rewriter/), this tutorial will demonstrate how to conditionally handle the [client-side widget](/turnstile/get-started/client-side-rendering/) and [Siteverify API](/turnstile/get-started/server-side-validation/) when specific criteria are met. :::note While this tutorial removes Turnstile client-side elements when specific criteria are met, you could instead conditionally insert them. ::: :::caution -It is critical to make sure you are validating tokens with the siteverify API when your criteria for enforcing Turnstile are not met. +It is critical to make sure you are validating tokens with the Siteverify API when your criteria for enforcing Turnstile are not met. It is not sufficient to only remove the client-side widget from the page, as an attacker can forge the request to your API. ::: diff --git a/src/content/docs/turnstile/tutorials/implicit-vs-explicit-rendering.mdx b/src/content/docs/turnstile/tutorials/implicit-vs-explicit-rendering.mdx index acaac657de76091..81468371ba198b0 100644 --- a/src/content/docs/turnstile/tutorials/implicit-vs-explicit-rendering.mdx +++ b/src/content/docs/turnstile/tutorials/implicit-vs-explicit-rendering.mdx @@ -39,7 +39,7 @@ To set up implicit rendering: ```html
``` -Once a challenge has been solved, a token is passed to the success callback. This token must be validated against our [siteverify endpoint](/turnstile/get-started/server-side-validation/). +Once a challenge has been solved, a token is passed to the success callback. This token must be validated against our [Siteverify endpoint](/turnstile/get-started/server-side-validation/). 3. **Create Your Form**: Turnstile is often used to protect forms on websites such as login forms or contact forms. You can embed the widget within your `
` tag. @@ -180,9 +180,9 @@ This will not call any callback and will remove all related DOM elements. ## Server-side validation -Regardless of the rendering method, Turnstile tokens need to be verified using `siteverify` because the front-end widget creates a cryptographically secured token. To ensure that a token is not forged by an attacker or has not been consumed yet, it is necessary to check the validity of the token using Cloudflare's siteverify API. +Regardless of the rendering method, Turnstile tokens need to be verified using Siteverify because the front-end widget creates a cryptographically secured token. To ensure that a token is not forged by an attacker or has not been consumed yet, it is necessary to check the validity of the token using Cloudflare's siteverify API. -The `siteverify` API will only validate a token once. If a token has already been checked, the siteverify API will yield an error on subsequent verification attempts indicating that a token has already been consumed. +The Siteverify API will only validate a token once. If a token has already been checked, the Siteverify API will yield an error on subsequent verification attempts indicating that a token has already been consumed. ```js // This is the demo secret key. In prod, we recommend you store diff --git a/src/content/docs/turnstile/tutorials/login-pages.mdx b/src/content/docs/turnstile/tutorials/login-pages.mdx index b150ba67579ab34..48a0c6c69774b50 100644 --- a/src/content/docs/turnstile/tutorials/login-pages.mdx +++ b/src/content/docs/turnstile/tutorials/login-pages.mdx @@ -12,7 +12,7 @@ sidebar: --- -This tutorial will guide you through integrating Cloudflare Turnstile to protect your web forms, such as login, signup, or contact forms. Learn how to implement the Turnstile widget on the client side and verify the Turnstile token via the siteverify API on the server side. +This tutorial will guide you through integrating Cloudflare Turnstile to protect your web forms, such as login, signup, or contact forms. Learn how to implement the Turnstile widget on the client side and verify the Turnstile token via the Siteverify API on the server side. ## Before you begin diff --git a/src/content/docs/workers/examples/turnstile-html-rewriter.mdx b/src/content/docs/workers/examples/turnstile-html-rewriter.mdx index 01fae3806e4afd8..1874f23c35eaddb 100644 --- a/src/content/docs/workers/examples/turnstile-html-rewriter.mdx +++ b/src/content/docs/workers/examples/turnstile-html-rewriter.mdx @@ -246,7 +246,7 @@ async def on_fetch(request, env): :::note -This is only half the implementation for Turnstile. The corresponding token that is a result of a widget being rendered also needs to be verified using the [siteverify API](/turnstile/get-started/server-side-validation/). Refer to the example below for one such implementation. +This is only half the implementation for Turnstile. The corresponding token that is a result of a widget being rendered also needs to be verified using the [Siteverify API](/turnstile/get-started/server-side-validation/). Refer to the example below for one such implementation. ::: diff --git a/src/content/partials/cloudflare-challenges/create-challenge-page.mdx b/src/content/partials/cloudflare-challenges/create-challenge-page.mdx new file mode 100644 index 000000000000000..a4d3b6a8833f777 --- /dev/null +++ b/src/content/partials/cloudflare-challenges/create-challenge-page.mdx @@ -0,0 +1,8 @@ +--- +{} + +--- + +You can implement a Challenge Page to your website or application by creating a [WAF custom rule](/waf/custom-rules/). + +Challenges are triggered by a rule in the [Web Application Firewall (WAF)](/waf/), [Bot Management](/bots/), or [Rate limiting](/waf/rate-limiting-rules/). \ No newline at end of file diff --git a/src/content/partials/turnstile/siteverify-warning.mdx b/src/content/partials/turnstile/siteverify-warning.mdx index 77b83cc83234bce..4e5b0a232868dfd 100644 --- a/src/content/partials/turnstile/siteverify-warning.mdx +++ b/src/content/partials/turnstile/siteverify-warning.mdx @@ -4,7 +4,7 @@ --- :::caution[Warning] -It is critical to enforce Turnstile tokens with the siteverify API. The Turnstile token could be invalid, expired, or already redeemed. Not verifying the token will leave major vulnerabilities in your implementation. +It is critical to enforce Turnstile tokens with the Siteverify API. The Turnstile token could be invalid, expired, or already redeemed. Not verifying the token will leave major vulnerabilities in your implementation. -You **must** call siteverify to complete your Turnstile configuration. Otherwise, it is incomplete and will result in zeroes for token validation when viewing your metrics in [Turnstile Analytics](/turnstile/turnstile-analytics/). +You **must** call Siteverify to complete your Turnstile configuration. Otherwise, it is incomplete and will result in zeroes for token validation when viewing your metrics in [Turnstile Analytics](/turnstile/turnstile-analytics/). ::: diff --git a/src/content/partials/turnstile/siteverify.mdx b/src/content/partials/turnstile/siteverify.mdx index 84e05cec455cc97..59ba0e6f92f190a 100644 --- a/src/content/partials/turnstile/siteverify.mdx +++ b/src/content/partials/turnstile/siteverify.mdx @@ -3,7 +3,7 @@ --- -It is important to [call the siteverify API](/turnstile/get-started/server-side-validation/). Without calling siteverify API to validate the tokens, your website or application is not protected. Skipping token validation means you cannot confirm the visitor's legitimacy. +It is important to [call the Siteverify API](/turnstile/get-started/server-side-validation/). Without calling Siteverify API to validate the tokens, your website or application is not protected. Skipping token validation means you cannot confirm the visitor's legitimacy. - Tokens can only be redeemed once. Even valid tokens will return `success:false` if they are reused, preventing token theft and replay attacks. - Tokens expire after five minutes. Validation must occur within this window to be effective. diff --git a/src/content/partials/turnstile/turnstile/siteverify-warning.mdx b/src/content/partials/turnstile/turnstile/siteverify-warning.mdx index 1f0be698c2a4ef5..6726a52e6521168 100644 --- a/src/content/partials/turnstile/turnstile/siteverify-warning.mdx +++ b/src/content/partials/turnstile/turnstile/siteverify-warning.mdx @@ -5,5 +5,5 @@ :::caution[Warning] -It is critical to enforce Turnstile tokens with the siteverify API. The Turnstile token could be invalid, expired, or already redeemed. Not verifying the token will leave major vulnerabilities in your implementation. +It is critical to enforce Turnstile tokens with the Siteverify API. The Turnstile token could be invalid, expired, or already redeemed. Not verifying the token will leave major vulnerabilities in your implementation. :::