Skip to content
Merged
Show file tree
Hide file tree
Changes from 18 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
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
1 change: 1 addition & 0 deletions public/_redirects
Original file line number Diff line number Diff line change
Expand Up @@ -1240,6 +1240,7 @@
/turnstile/migration/migrating-from-recaptcha/ /turnstile/migration/recaptcha/ 301
/turnstile/migration/migrating-from-hcaptcha/ /turnstile/migration/hcaptcha/ 301
/turnstile/concepts/widget-types/ /turnstile/concepts/widget/ 301
/turnstile/concepts/domain-management/ /turnstile/concepts/hostname-management/ 301

# waf
/waf/about/ /waf/concepts/ 301
Expand Down
31 changes: 0 additions & 31 deletions src/content/docs/turnstile/concepts/domain-management.mdx

This file was deleted.

19 changes: 19 additions & 0 deletions src/content/docs/turnstile/concepts/ephemeral-id.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
title: Ephemeral IDs
pcx_content_type: reference
sidebar:
order: 4

---

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.

Ephemeral IDs are not unique and have a lifespan of up to a few days. These IDs cannot be used to track a single visitor over multiple days as they change frequently.

Refer to the [blog post](https://blog.cloudflare.com/turnstile-ephemeral-ids-for-fraud-detection/) for more information.

## Availability

Ephemeral IDs are available to customers with Enterprise Bot Management and Enterprise Turnstile.
36 changes: 36 additions & 0 deletions src/content/docs/turnstile/concepts/hostname-management.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
title: Hostname management
pcx_content_type: reference
sidebar:
order: 2

---

By default, all widgets can have up to 10 hostnames associated with a widget. A widget requires at least one hostname to be entered.

Only Enterprise Bot Management and Enterprise Turnstile customers can have this limit increased. Contact your account team to increase your hostname limit.

You must specify a list of hostnames when creating a widget. The widget can only be used on these hostnames and will not work on any other hostnames. You can use subdomains to restrict the widgets further.

The hostname should not contain a scheme `http://` or `https://`, a port `443`, or a path `/`.

Specifying a subdomain is optional.

For example, using the `www.example.com` value will allow widgets on the following hostnames:

- `www.example.com`
- `abc.www.example.com:8080`

but not on the following hostnames:

- `example.com`
- `dash.example.com`
- `cloudflare.com`

When the widget is embedded on a hostname not listed, it will show an error message.

## Optional hostname validation

Customers with Enterprise Bot Management and Enterprise Turnstile can have the optional `any hostname` validation entitlement.

By default, a widget requires at least one hostname to be entered. With this entitlement, you can create and use a widget without entering any hostnames for the widget. Contact your account team to enable this entitlement.
34 changes: 23 additions & 11 deletions src/content/docs/turnstile/concepts/widget.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,49 +20,61 @@ Widgets can be implemented in normal, flexible, or compact sizes.

Refer to [widget sizes](/turnstile/get-started/client-side-rendering/#widget-size) for an example on how to configure flexible or compact mode.

## Managed (recommended)
:::note[Offlabel]
Customers with Enterprise Bot Management and Enterprise Turnstile have the ability to remove the Cloudflare branding and customize the Turnstile widget.
:::

## Availability

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.

## Widget types

### Managed (recommended)

This mode is fully managed by Cloudflare. It automatically chooses the appropriate action based on various signals and risk levels. Cloudflare will use the information from the visitor to decide if an interactive challenge should be used. Turnstile will only require interaction if a further check is necessary to verify that the visitor is human. When an interaction is required, the user will be prompted to check a box (no images or text to decipher). This managed mode is ideal for users who want a simple configuration without needing to fine-tune the behavior.

### Light mode
#### Light mode

![Managed challenge](~/assets/images/turnstile/light-regular.png)
![Verifying the challenge](~/assets/images/turnstile/light-verifying.png)
![Successful managed challenge](~/assets/images/turnstile/light-success.png)

### Dark mode
#### Dark mode

![Managed challenge](~/assets/images/turnstile/dark-regular.png)
![Verifying the challenge](~/assets/images/turnstile/dark-verifying.png)
![Successful managed challenge](~/assets/images/turnstile/dark-success.png)

## Compact mode
### Compact mode

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

### Light mode
#### Light mode

![Compact managed challenge](~/assets/images/turnstile/light-compact.png)

### Dark mode
#### Dark mode

![Compact managed challenge](~/assets/images/turnstile/dark-compact.png)

## Non-Interactive
### Non-Interactive

Visitors will see a widget with a loading bar while the browser challenges run. Unlike managed mode, visitors will never be required or prompted to interact with the widget. This mode is ideal for users who want to prioritize visitor experience and do not want to add any friction with a Turnstile interaction.

### Light mode
#### Light mode

![Verifying the challenge](~/assets/images/turnstile/light-verifying.png)
![Successful managed challenge](~/assets/images/turnstile/light-success.png)

### Dark mode
#### Dark mode

![Verifying the challenge](~/assets/images/turnstile/dark-verifying.png)
![Successful managed challenge](~/assets/images/turnstile/dark-success.png)

## Invisible
### Invisible

This mode is similar to non-interactive mode where visitors will never interact with the Turnstile widget. Visitors will not see a widget or any indication that an invisible browser challenge is in progress. Invisible challenges should take a few seconds to complete.

Expand Down Expand Up @@ -92,4 +104,4 @@ The widget expires when a token was issued but the user did not solve the challe

![Unsupported browser](~/assets/images/turnstile/unsupported-browser.png)

Visitors with outdated browsers or unsupported browsers will encouter this widget state. Refer to [Supported browsers](/waf/reference/cloudflare-challenges/#browser-support) for more information regarding supported browsers.
Visitors with outdated browsers or unsupported browsers will encouter this widget state. Refer to [Supported browsers](/waf/reference/cloudflare-challenges/#browser-support) for more information regarding supported browsers.
6 changes: 6 additions & 0 deletions src/content/docs/turnstile/frequently-asked-questions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,23 @@ sidebar:

---

## What features are available for Free or Enterprise users?

Refer to [Availability](/turnstile/#availability) for more information on features available per tier.

---

## What languages does Turnstile support?

Refer to the [list of supported languages](/turnstile/reference/supported-languages/) for more information.

---

## Does Turnstile conform to WCAG 2.1 Level AA accessibility standard?

Yes, Turnstile is WCAG 2.1 Level AA compliant.

---

## Where can I get additional support for Turnstile?

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,8 @@ It always contains a `success` property, either true or false, indicating whethe
"hostname": "example.com",
"error-codes": [],
"action": "login",
"cdata": "sessionid-123456789"
"cdata": "sessionid-123456789",
"ephemeral_id": false
}
```

Expand All @@ -269,6 +270,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.
- `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:

Expand Down
3 changes: 3 additions & 0 deletions src/content/docs/turnstile/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ head:
import {
Description,
Feature,
FeatureTable,
LinkButton,
Plan,
RelatedProduct,
Expand Down Expand Up @@ -53,6 +54,8 @@ Turnstile is WCAG 2.1 AA compliant.

## Availability

<FeatureTable id="security.turnstile" />

Refer to [Cloudflare Turnstile's product page](https://www.cloudflare.com/products/turnstile/) for more information on Turnstile's plans.

---
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/turnstile/troubleshooting/testing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import { GlossaryTooltip } from "~/components"

The following <GlossaryTooltip term="sitekey">sitekeys</GlossaryTooltip> and <GlossaryTooltip term="secret key">secret keys</GlossaryTooltip> are available for testing. It is recommended that you use these keys in your development environment to ensure the challenges running in Turnstile do not conflict with your developer tools.

To test locally with real keys, you need to add your testing hostnames (like `localhost`) to your [domain allowlist](/turnstile/concepts/domain-management/).
To test locally with real keys, you need to add your testing hostnames (like `localhost`) to your [domain allowlist](/turnstile/concepts/hostname-management/).

Dummy sitekeys can be used from any domain, including on `localhost`.

Expand Down
47 changes: 47 additions & 0 deletions src/content/plans/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -2010,6 +2010,53 @@
"ent": 200
}
}
},
"turnstile": {
"title": "Turnstile",
"link": "/turnstile/",
"properties": {
"widgets": {
"title": "Number of widgets",
"link": "/turnstile/concepts/widget/",
"free": "10 widgets",
"ent": "Unlimited"
},
"modes": {
"title": "Interactivity modes",
"link": "/turnstile/get-started/client-side-rendering/#appearance-modes",
"free": "Managed, Invisible, Interactive",
"ent": "Managed, Invisible, Interactive"
},
"offlabel": {
"title": "Offlabel (remove Cloudflare branding)",
"free": "No",
"ent": "Yes"
},
"preclearance": {
"title": "Pre-clearance support",
"link": "/turnstile/concepts/pre-clearance-support/",
"free": "Yes",
"ent": "Yes"
},
"hostname_validation": {
"title": "Hostname validation",
"link": "/turnstile/concepts/hostname-management/",
"free": "10 hostnames per widget",
"ent": "200 hostnames per widget. <br> The `any hostname` entitlement removes hostname as a requirement and allows you to use the widget anywhere."
},
"graphql_analytics": {
"title": "Analytics time window",
"link": "/turnstile/turnstile-analytics/",
"free": "30 days maximum",
"ent": "30 days maximum"
},
"ephemeral_ids": {
"title": "Ephemeral IDs",
"link": "/turnstile/concepts/ephemeral-id/",
"free": "No",
"ent": "Yes"
}
}
}
},
"scrape_shield": {
Expand Down
Loading