diff --git a/public/_redirects b/public/_redirects index 6e85b09aa301a52..f7bcd1e67857a85 100644 --- a/public/_redirects +++ b/public/_redirects @@ -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 diff --git a/src/content/docs/turnstile/concepts/domain-management.mdx b/src/content/docs/turnstile/concepts/domain-management.mdx deleted file mode 100644 index d351953f014225b..000000000000000 --- a/src/content/docs/turnstile/concepts/domain-management.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Domain management -pcx_content_type: reference -sidebar: - order: 2 - ---- - -You must specify a list of domains when creating a widget. The widget can only be used on these domains and will not work on any other domains. You can use subdomains to restrict the widgets further. - -The domain 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 domains: - -- `www.example.com` -- `abc.www.example.com:8080` - -but not on the following domains: - -- `example.com` -- `dash.example.com` -- `cloudflare.com` - -When the widget is embedded on a domain not listed, it will show an error message. - -:::note - -Enterprise Bot Management customers can remove the hostname validation requirement for a widget. For more information on this feature, contact your account team. -::: diff --git a/src/content/docs/turnstile/concepts/ephemeral-id.mdx b/src/content/docs/turnstile/concepts/ephemeral-id.mdx new file mode 100644 index 000000000000000..272a8605427f44d --- /dev/null +++ b/src/content/docs/turnstile/concepts/ephemeral-id.mdx @@ -0,0 +1,23 @@ +--- +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 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. + +Refer to the [blog post](https://blog.cloudflare.com/turnstile-ephemeral-ids-for-fraud-detection/) for more information. + +## Availability + +Ephemeral IDs are available to Enterprise Bot Management customers with the Enterprise Turnstile add-on or standalone Enterprise Turnstile customers. Contact your account team for access to Ephemeral IDs. + +## Enablement + +After your account team enables the Ephemeral ID entitlement, you must turn it on for the widget that you want the Ephemeral ID on via the [API call](/api/resources/turnstile/subresources/widgets/methods/update/). \ No newline at end of file diff --git a/src/content/docs/turnstile/concepts/hostname-management.mdx b/src/content/docs/turnstile/concepts/hostname-management.mdx new file mode 100644 index 000000000000000..afa6ac418dab30b --- /dev/null +++ b/src/content/docs/turnstile/concepts/hostname-management.mdx @@ -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 or 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. diff --git a/src/content/docs/turnstile/concepts/widget.mdx b/src/content/docs/turnstile/concepts/widget.mdx index bf181251bb7a029..f0a2b813758a072 100644 --- a/src/content/docs/turnstile/concepts/widget.mdx +++ b/src/content/docs/turnstile/concepts/widget.mdx @@ -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. @@ -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. \ No newline at end of file diff --git a/src/content/docs/turnstile/frequently-asked-questions.mdx b/src/content/docs/turnstile/frequently-asked-questions.mdx index 32c54dc4191cd62..c4416e86c64ba95 100644 --- a/src/content/docs/turnstile/frequently-asked-questions.mdx +++ b/src/content/docs/turnstile/frequently-asked-questions.mdx @@ -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? 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 68b2a6c7d0b362d..caf1e6c41d434ce 100644 --- a/src/content/docs/turnstile/get-started/server-side-validation.mdx +++ b/src/content/docs/turnstile/get-started/server-side-validation.mdx @@ -258,7 +258,10 @@ 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", + "metadata":{ + "ephemeral_id": "x:9f78e0ed210960d7693b167e" + } } ``` @@ -269,6 +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. In case of a validation failure, the response should be similar to the following: diff --git a/src/content/docs/turnstile/index.mdx b/src/content/docs/turnstile/index.mdx index 38ff4c4c09a9c3f..94218564798b54b 100644 --- a/src/content/docs/turnstile/index.mdx +++ b/src/content/docs/turnstile/index.mdx @@ -11,6 +11,7 @@ head: import { Description, Feature, + FeatureTable, LinkButton, Plan, RelatedProduct, @@ -53,6 +54,8 @@ Turnstile is WCAG 2.1 AA compliant. ## Availability + + Refer to [Cloudflare Turnstile's product page](https://www.cloudflare.com/products/turnstile/) for more information on Turnstile's plans. --- diff --git a/src/content/docs/turnstile/troubleshooting/testing.mdx b/src/content/docs/turnstile/troubleshooting/testing.mdx index 5537889f430828b..535c90511051169 100644 --- a/src/content/docs/turnstile/troubleshooting/testing.mdx +++ b/src/content/docs/turnstile/troubleshooting/testing.mdx @@ -12,7 +12,7 @@ import { GlossaryTooltip } from "~/components" The following sitekeys and secret keys 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`. diff --git a/src/content/plans/index.json b/src/content/plans/index.json index 725e834c07a20df..fcbf1aaea9a5f01 100644 --- a/src/content/plans/index.json +++ b/src/content/plans/index.json @@ -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": "Maximum of 200 hostnames per widget.
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": {