Features for integration with WAF service providers

This document helps you understand the features of reCAPTCHA Enterprise for WAF and determine which feature best matches your use case.

reCAPTCHA Enterprise for WAF offers the following features that you can use to integrate with web application firewall (WAF) service providers:

• reCAPTCHA action-tokens
• reCAPTCHA session-tokens
• reCAPTCHA challenge page
• reCAPTCHA WAF express protection

Features overview

The following table shows a brief comparison of reCAPTCHA action-tokens, reCAPTCHA session-tokens, reCAPTCHA challenge page, and reCAPTCHA WAF express protection:

Note: Only reCAPTCHA action-tokens are supported for the integration of mobile applications with Google Cloud Armor.

Comparison category	reCAPTCHA action-tokens	reCAPTCHA session-tokens	reCAPTCHA challenge page	reCAPTCHA WAF express protection
Use case	Use reCAPTCHA action-tokens to protect user actions, such as login or comment posts.	Use reCAPTCHA session-tokens to protect the whole user session on the site's domain.	Use reCAPTCHA challenge page when you suspect spam activity directed to your site and you need to screen out bots. This method interrupts a user's activity because the user has to verify a CAPTCHA challenge.	Use reCAPTCHA WAF express protection when your environment does not support the integration of the reCAPTCHA JavaScript or the mobile SDKs.
Supported platforms	Websites and mobile applications	Websites	Websites	APIs, websites, mobile applications, and IoT devices such as TVs and gaming consoles
Integration effort	Medium Integration requires you to do the following: Install the reCAPTCHA JavaScript on the individual pages of your site or install the reCAPTCHA Enterprise mobile SDK on your mobile application. Attach the action-token to the individual request header. Configure Google Cloud Armor security policy rules, or reCAPTCHA firewall policies for third-party WAF service providers.	Medium Integration requires you to do the following: Install the reCAPTCHA JavaScript on the individual pages of your site. Configure Google Cloud Armor security policy rules, or reCAPTCHA firewall policies for third-party WAF service providers.	Low Integration requires you to configure security policy rules for Google Cloud Armor, or reCAPTCHA firewall policies for third-party WAF service providers.	Low Integration requires you to either configure reCAPTCHA WAF express protection with a WAF service provider or make a request from your application server to reCAPTCHA Enterprise.
Detection accuracy	Highest An action-token protects individual user actions.	High A session-token protects the whole user session on the site's domain.	Medium The process involves redirects to the reCAPTCHA challenge page, which might not receive all the page-specific signals. As a result, bot detection might be less accurate.	Low Client-side signals are not available.
Supported reCAPTCHA version	reCAPTCHA Enterprise score-based and checkbox keys	reCAPTCHA Enterprise score-based keys	reCAPTCHA challenge page uses the optimized version of reCAPTCHA to minimize the integration.	reCAPTCHA Enterprise score-based keys

You can use one or more features of reCAPTCHA Enterprise for WAF in a single application. For example, you can choose to apply a session-token for all pages, and based on the session-token's score, you can redirect suspicious requests to the reCAPTCHA challenge page. Also, you can use an action-token for high-profile actions, such as checkout. For more information, see examples.

reCAPTCHA action-tokens

You can use reCAPTCHA action-tokens to protect important user interactions, such as checkout on web pages and on mobile applications.

Note: Only reCAPTCHA action-tokens are supported for integrating reCAPTCHA Enterprise for WAF with Google Cloud Armor on mobile applications.

reCAPTCHA action-tokens workflow consists of the following steps:

1. When an end user triggers an action protected by reCAPTCHA Enterprise, the web page or the mobile application sends signals that are collected in the browser to reCAPTCHA Enterprise for analysis.
2. reCAPTCHA Enterprise sends an action-token to the web page or the mobile application.
3. You attach this action-token to the header of the request that you want to protect.
4. When the end user requests access with the action-token, the WAF service provider decodes and validates the action-token attributes instead of your backend application.
5. The WAF service provider applies actions based on your configured security policy rules or firewall policy rules, whichever is applicable.

The following sequence diagram shows the reCAPTCHA action-tokens workflow for websites:

Google Cloud Armor

Third-party WAF service provider

The following sequence diagram shows the reCAPTCHA action-tokens workflow for mobile applications:

reCAPTCHA session-tokens

You can use reCAPTCHA session-tokens when you want to protect the whole user session on the site's domain. A session token lets you reuse an existing reCAPTCHA Enterprise assessment for a specified period, so that no further assessments are necessary for a particular user, reducing user friction, and total required reCAPTCHA calls.

To enable reCAPTCHA Enterprise to learn about the browsing pattern of your end users, we recommend that you use a reCAPTCHA session-token on all the web pages of your site.

reCAPTCHA session-tokens workflow consists of the following steps:

1. The browser loads the reCAPTCHA JavaScript from reCAPTCHA Enterprise.
2. The reCAPTCHA JavaScript sets a session-token as a cookie on the end-user's browser after the assessment.
3. The end-user's browser stores the cookie and reCAPTCHA JavaScript refreshes the cookie every 30 minutes as long as the reCAPTCHA JavaScript remains active.
4. When the user requests access with the cookie, WAF service provider validates this cookie and applies actions based on the security policy rules or firewall policy rules.

The following sequence diagram shows the reCAPTCHA session-tokens workflow:

Google Cloud Armor

Third-party WAF service provider

reCAPTCHA challenge page

You can use the reCAPTCHA challenge page feature to redirect incoming requests to reCAPTCHA Enterprise to determine whether each request is potentially fraudulent or legitimate.

This application of a redirect and possible CAPTCHA challenge interrupts a user's activity. We recommend using it to screen out bots when you suspect spam activity directed to your site.

When an end user (user) visits your site for the first time, the following events take place:

1. At the WAF layer, the user's request is redirected to reCAPTCHA Enterprise challenge page.
2. reCAPTCHA Enterprise responds with an HTML page embedded with the reCAPTCHA JavaScript.
3. When the challenge page is rendered, reCAPTCHA Enterprise assesses the user interaction. If necessary, reCAPTCHA Enterprise serves a CAPTCHA challenge to the user.

4. Depending on the result of the assessment, reCAPTCHA Enterprise does the following:

   1. If the user interaction passes the assessment, reCAPTCHA Enterprise issues an exemption cookie. The browser attaches this exemption cookie to the user's subsequent requests to the same site until the cookie expires. By default, the exemption cookie expires after three hours.
   2. If the user interaction does not pass the assessment, reCAPTCHA Enterprise does not issue an exemption cookie.

5. reCAPTCHA Enterprise reloads the web page with the exemption cookie if the user accesses the web page using a GET/HEAD call. If the user accesses the web page using a POST/PUT call, then the user needs to click the reload link on the page.

6. The WAF service provider exempts requests that have a valid exemption cookie from being redirected again and grants access to your site.

The following sequence diagram shows the reCAPTCHA challenge page workflow:

Google Cloud Armor

Third-party WAF service provider

reCAPTCHA WAF express protection

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

You can use reCAPTCHA WAF express protection (reCAPTCHA WAF express) to protect your applications in an environment that does not support running of reCAPTCHA JavaScript or native mobile SDKs, for example, IoT devices and set-top boxes. You can set up reCAPTCHA WAF express at the WAF layer with a WAF service provider or in a standalone environment on an application server. reCAPTCHA WAF express uses only backend signals to generate a reCAPTCHA risk score.

Note: Because reCAPTCHA WAF express is in the Preview phase, it might return fewer score buckets and classification reasons than reCAPTCHA Enterprise for the web.

The reCAPTCHA WAF express workflow consists of the following steps:

1. When a user requests access for a web page, the WAF service provider or the application server creates an assessment request to reCAPTCHA Enterprise.
2. reCAPTCHA Enterprise assess the user interaction and sends a risk score.
3. Based on the risk score, the WAF service provider or the application server allows or blocks the access.

The following sequence diagram shows the reCAPTCHA WAF express workflow:

What's next

• Learn about the token attributes for Google Cloud Armor.
• Integrate reCAPTCHA Enterprise for WAF with Google Cloud Armor on websites.
• Integrate reCAPTCHA Enterprise for WAF with Google Cloud Armor on mobile applications.
• Learn about the token attributes for Fastly.
• Integrate reCAPTCHA Enterprise for WAF with Fastly.
• Set up reCAPTCHA WAF express protection on an application server.