Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/content/docs/turnstile/concepts/ephemeral-id.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ sidebar:

Ephemeral IDs generate a unique short-lived ID that can link behavior to a specific client instead of an IP address without relying on setting any cookies or using similar client-side storage.

When the same visitor interacts with Turnstile widgets from different Cloudflare customers, they receive different Ephemeral IDs for each contact. In attacks where fraudsters attempt to disguise themselves using different IP addresses, Ephemeral IDs detect abuse patterns more accurately than determining whether the visitor is a human or a bot.
When the same visitor interacts with Turnstile widgets from different Cloudflare customers, they receive different Ephemeral IDs for each contact. In attacks where fraudsters attempt to disguise themselves using different IP addresses, Ephemeral IDs detect abuse patterns more accurately than determining whether the visitor is a human or a bot.

Ephemeral IDs are not unique and have a lifespan of up to a few days. They can be useful for identifying a bad actor in acute attacks such as sudden spikes in fake account creations or credential stuffing.

Expand Down
6 changes: 3 additions & 3 deletions src/content/docs/turnstile/concepts/hostname-management.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,13 @@ Only Enterprise Bot Management and Enterprise Turnstile customers can have this

## Add a custom hostname

You can add a hostname to your Turnstile widget even if it is not on the Cloudflare network or registered as a zone. There are no prerequisites for using Turnstile.
You can add a hostname to your Turnstile widget even if it is not on the Cloudflare network or registered as a zone. There are no prerequisites for using Turnstile.

To add a custom hostname:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Go to **Turnstile**.
3. On an existing widget, select **Settings**.
3. On an existing widget, select **Settings**.
4. Select **Add Hostnames** under Hostname Management.
5. Add a custom hostname or choose from an existing hostname.
6. Select **Add**.
Expand All @@ -42,7 +42,7 @@ When associating hostnames with a widget, follow these requirements:
- A port (for example, `443`)
- A path (for example, `/path`)

### Subdomain specification
### Subdomain specification

Specifying a subdomain is optional, but it can be used to further restrict the widget. For example, adding `www.example.com` as a hostname will allow widgets to work on:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,22 @@ sidebar:

---

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.
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`
- `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.
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.
Expand Down
14 changes: 7 additions & 7 deletions src/content/docs/turnstile/concepts/widget.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ Every instance of Turnstile belongs to a Turnstile widget. It is configured on a

The 3 modes for Turnstile are **Managed**, **Non-Interactive**, and **Invisible**.

Refer to [appearance modes](/turnstile/get-started/client-side-rendering/#appearance-modes) to configure whether to have the widget be always visible or visible only when interaction is required.
Refer to [appearance modes](/turnstile/get-started/client-side-rendering/#appearance-modes) to configure whether to have the widget be always visible or visible only when interaction is required.

Widgets can be implemented in normal, flexible, or compact sizes.
Widgets can be implemented in normal, flexible, or compact sizes.

<Render file="widget-size" />

Expand All @@ -24,9 +24,9 @@ Refer to [widget sizes](/turnstile/get-started/client-side-rendering/#widget-siz
Customers with Enterprise Bot Management and Enterprise Turnstile have the ability to remove the Cloudflare branding and customize the Turnstile widget.
:::

## Availability
## Availability

Free users are limited to 10 widgets per account.
Free users are limited to 10 widgets per account.

Customers with Enterprise Bot Management and Enterprise Turnstile can have this limit increased. Contact your account team to increase your widget limit.

Expand All @@ -50,7 +50,7 @@ This mode is fully managed by Cloudflare. It automatically chooses the appropria

### Compact mode

You can configure the Turnstile widget in compact mode, which functions in the same way as a Managed widget.
You can configure the Turnstile widget in compact mode, which functions in the same way as a Managed widget.

#### Light mode

Expand Down Expand Up @@ -84,15 +84,15 @@ This mode is similar to non-interactive mode where visitors will never interact

![Unknown error state](~/assets/images/turnstile/unknown-error-state.png)

When an unknown error occurs during the challenge, visitors will encounter this widget state. Visitors can refresh and retry the challenge. If the error persists, they can submit a feedback form by selecting **Send feedback** on the widget.
When an unknown error occurs during the challenge, visitors will encounter this widget state. Visitors can refresh and retry the challenge. If the error persists, they can submit a feedback form by selecting **Send feedback** on the widget.

Refer to [Feedback reports](/turnstile/troubleshooting/feedback-reports) for more information.

### Interaction timed out state

![Interaction timed out](~/assets/images/turnstile/interaction-timed-out.png)

When the challenge is not solved for an extended period of time, it must be issued again by reloading the page or the widget.
When the challenge is not solved for an extended period of time, it must be issued again by reloading the page or the widget.

### Challenge timed out state

Expand Down
12 changes: 6 additions & 6 deletions src/content/docs/turnstile/extensions/google-firebase.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@ Turnstile is [available as an extension](https://extensions.dev/extensions/cloud

Google Firebase is a comprehensive app development platform that provides a variety of tools and services to help developers build, improve, and grow their mobile and web applications.

Firebase App Check helps protect Firebase resources like Cloud Firestore, Realtime Database, Cloud Storage, and Functions from abuse, such as automated fraud attacks and denial of service (DoS) attacks, by ensuring that incoming requests are from legitimate visitors and trusted sources.
Firebase App Check helps protect Firebase resources like Cloud Firestore, Realtime Database, Cloud Storage, and Functions from abuse, such as automated fraud attacks and denial of service (DoS) attacks, by ensuring that incoming requests are from legitimate visitors and trusted sources.

## Set up a Google Firebase project

1. Create a Firebase project by going to the [Firebase Console](https://console.firebase.google.com/).
2. Select **Add Project** and follow the prompts to create a new project.
3. Add an app to your project by selecting your project.
4. In the project overview, select **Add App** and choose the platform: **Web**.
5. [Register your app](https://firebase.google.com/docs/web/setup?hl=en&authuser=0#register-app) and follow the guide to get your Firebase configuration.
5. [Register your app](https://firebase.google.com/docs/web/setup?hl=en&authuser=0#register-app) and follow the guide to get your Firebase configuration.

:::note

Expand All @@ -28,7 +28,7 @@ It is important to register your web app first to connect it with Turnstile late

## Set up Cloudflare Turnstile

1. Create a Cloudflare Turnstile site by going to the [Cloudflare Turnstile dashboard](https://dash.cloudflare.com/?to=/:account/turnstile).
1. Create a Cloudflare Turnstile site by going to the [Cloudflare Turnstile dashboard](https://dash.cloudflare.com/?to=/:account/turnstile).
2. Create a new widget and get the [sitekey and secret key](/turnstile/get-started/#get-a-sitekey-and-secret-key).
- The domain you configure with the Turnstile widget should be the domain of your web app.
- The [widget mode](/turnstile/concepts/widget/) must be **Invisible**.
Expand All @@ -43,7 +43,7 @@ It is important to register your web app first to connect it with Turnstile late
4. Enter the secret key from Cloudflare Turnstile and your Firebase App ID.
5. Select **Install extension**.

### Grant access to the Cloudflare extension
### Grant access to the Cloudflare extension

1. Grant access to the Cloudflare extension under the IAM section of your project by selecting **Grant Access** under **View by Principals**.
2. Select `ext-cloudflare-turnstile` from the dropdown menu.
Expand Down Expand Up @@ -88,9 +88,9 @@ cpo.getToken().then(({ token }) => {

```

### Verify the App Check token in your web application
### Verify the App Check token in your web application

To verify the App Check token in your web application, refer to Firebase's [Token Verification guide](https://firebase.google.com/docs/app-check/custom-resource-backend?hl=en#verification).
To verify the App Check token in your web application, refer to Firebase's [Token Verification guide](https://firebase.google.com/docs/app-check/custom-resource-backend?hl=en#verification).

```js
import express from "express";
Expand Down
6 changes: 3 additions & 3 deletions src/content/docs/turnstile/get-started/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The sitekey and secret key are generated upon the creation of a widget, allowing

:::note

You can find special sitekeys to be used for testing in the [testing](/turnstile/troubleshooting/testing/) section.
You can find special sitekeys to be used for testing in the [testing](/turnstile/troubleshooting/testing/) section.
:::

### New sites
Expand All @@ -41,7 +41,7 @@ You can find special sitekeys to be used for testing in the [testing](/turnstile
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/turnstile) and select your account.
2. Go to **Turnstile**.
3. In the widget overview, select **Settings**.
4. Confirm the [hostnames](/turnstile/concepts/hostname-management/) configured.
4. Confirm the [hostnames](/turnstile/concepts/hostname-management/) configured.
5. (Optional) Opt in for [pre-clearance support](/turnstile/concepts/pre-clearance-support/).
6. Copy your sitekey and secret key.

Expand Down Expand Up @@ -73,5 +73,5 @@ Refer to [Server-side validation](/turnstile/get-started/server-side-validation/

:::note

Rendering the client-side integration & validating the server-side response are both necessary to allow Turnstile to function properly.
Rendering the client-side integration & validating the server-side response are both necessary to allow Turnstile to function properly.
:::
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ Any modifications to the environment, such as the User Agent, [Content Security

## WebView configurations

Turnstile requires specific WebView settings to function properly. For Android implementations, refer to [`setJavaScriptEnabled`](https://developer.android.com/reference/android/webkit/WebSettings#setJavaScriptEnabled(boolean)) to tell the WebView to enable JavaScript execution and [`setDomStorageEnabled`](https://developer.android.com/reference/android/webkit/WebSettings#setDomStorageEnabled(boolean)) to enable the DOM storage API.
Turnstile requires specific WebView settings to function properly. For Android implementations, refer to [`setJavaScriptEnabled`](https://developer.android.com/reference/android/webkit/WebSettings#setJavaScriptEnabled(boolean)) to tell the WebView to enable JavaScript execution and [`setDomStorageEnabled`](https://developer.android.com/reference/android/webkit/WebSettings#setDomStorageEnabled(boolean)) to enable the DOM storage API.

These settings ensure that the mobile WebView can properly load and execute the Turnstile challenge. If these configurations are missing, Turnstile may malfunction.

## Update allowed origins

In addition to ensuring proper WebView settings, if you have allowed origins configured, it is essential to update the list to include:
In addition to ensuring proper WebView settings, if you have allowed origins configured, it is essential to update the list to include:

```txt

Expand All @@ -32,11 +32,11 @@ challenges.cloudflare.com, about:blank, about:srcdoc
Only [React Native](https://github.com/react-native-webview/react-native-webview/blob/master/docs/Reference.md#originwhitelist) contains the allowed origins above by default.
:::

Without this, Turnstile challenges might fail to load. WebView should also be configured to allow insecure connections (`http` and `https`).
Without this, Turnstile challenges might fail to load. WebView should also be configured to allow insecure connections (`http` and `https`).

## Maintain a consistent user agent

When implementing Turnstile with WebViews, the user agent must stay consistent as changing the user agent will cause the challenges to fail.
When implementing Turnstile with WebViews, the user agent must stay consistent as changing the user agent will cause the challenges to fail.

## Use clearance cookies

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/turnstile/get-started/pre-clearance.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import { Render } from "~/components"

To enable pre-clearance, you must ensure that the hostname of the Turnstile widget matches the zone with the WAF rules. During the Turnstile configuration setup in the Cloudflare dashboard, you can see the registered zones. Select the appropriate hostname from this list.

The prerequisite is crucial for pre-clearance to function properly. If set up correctly, visitors who successfully solve Turnstile will receive a cookie with the security clearance level set by the customer. When encountering a WAF challenge on the same zone, they will bypass additional challenges for the configured clearance level and below.
The prerequisite is crucial for pre-clearance to function properly. If set up correctly, visitors who successfully solve Turnstile will receive a cookie with the security clearance level set by the customer. When encountering a WAF challenge on the same zone, they will bypass additional challenges for the configured clearance level and below.

For more details on managing hostnames, refer to the [Hostname Management documentation](/turnstile/concepts/hostname-management/).

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/turnstile/migration/hcaptcha.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ turnstile.render(element, {
Turnstile supports:

- the `render()` call
- hCaptcha invisible mode with the `execute()` call
- hCaptcha invisible mode with the `execute()` call
:::

## Server-side integration
Expand Down
8 changes: 4 additions & 4 deletions src/content/docs/turnstile/migration/recaptcha.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ To complete the migration, you must obtain the [sitekey and secret key](/turnsti

:::note

Turnstile migration is currently compatible up to reCAPTCHA v2.
Turnstile migration is currently compatible up to reCAPTCHA v2.
:::

## Client-side integration
Expand All @@ -32,7 +32,7 @@ enables the following features:

- implicit rendering for reCAPTCHA
- `g-recaptcha-response` input name for forms
- register the Turnstile API as `grecaptcha`
- register the Turnstile API as `grecaptcha`
:::

</div>
Expand All @@ -44,7 +44,7 @@ enables the following features:
Turnstile supports:

- the `render()` call
- reCAPTCHA v2 invisible mode with the `execute()` call
- reCAPTCHA v2 invisible mode with the `execute()` call
:::

## Server-side integration
Expand All @@ -57,5 +57,5 @@ reCAPTCHA supports `GET` requests using query parameters, i.e: `GET /siteverify?

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.
Refer to [server-side validation](/turnstile/get-started/server-side-validation/) for more information.
:::
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ We recommend validating your CSP with [Google's CSP Evaluator](https://csp-evalu

:::note

You cannot set your own CSP and/or Referer-Policy via meta tags or [Transform rules](/rules/transform/) in challenge pages.
You cannot set your own CSP and/or Referer-Policy via meta tags or [Transform rules](/rules/transform/) in challenge pages.
:::

## Pre-clearance support
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Turnstile supports `auto` (default), which uses the visitor's browser language i

:::note

To request Turnstile support for a language not listed below or submit feedback on a translation error, you can fill out [this form](https://forms.gle/Cdz4YTRoagGpVwd7A).
To request Turnstile support for a language not listed below or submit feedback on a translation error, you can fill out [this form](https://forms.gle/Cdz4YTRoagGpVwd7A).
:::

| Language | Language code<br/>(4 letters) | Language code<br/>(2 letters) |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ An error callback will retrieve an error code as its first parameter. Error code

:::note

When an error code is marked with `***`, it means that the remaining numbers can be ignored and are for internal use.
When an error code is marked with `***`, it means that the remaining numbers can be ignored and are for internal use.
:::

| <div style="width:130px">Error code</div> | Description | Retry | Troubleshooting |
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/turnstile/turnstile-analytics.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ View the history of your website’s widget Solve Rate with Turnstile analytics.

:::note

You can filter the data by `Action=(free input)` or by time.
You can filter the data by `Action=(free input)` or by time.
:::

### Visitor Solve Rate
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ function isTestEnvironment(request) {
const testIPs = ['127.0.0.1', '::1'];
const isTestIP = testIPs.includes(request.ip);
const hasTestHeader = request.headers['x-test-environment'] === 'secret-token';

return isTestIP || hasTestHeader;
}

Expand All @@ -53,7 +53,7 @@ function getTurnstileCredentials(request) {
secretKey: '1x0000000000000000000000000000000AA'
};
}

return {
sitekey: process.env.TURNSTILE_SITE_KEY,
secretKey: process.env.TURNSTILE_SECRET_KEY
Expand Down