This document helps you understand the features of reCAPTCHA for WAF and determine which feature best matches your use case.
reCAPTCHA for WAF offers the following features that you can use to integrate with web application firewall (WAF) service providers:
Features overview
The following table shows a brief comparison of reCAPTCHA action-tokens, reCAPTCHA session-tokens, reCAPTCHA challenge page, and reCAPTCHA express:
| Comparison category | reCAPTCHA action-tokens | reCAPTCHA session-tokens | reCAPTCHA challenge page | reCAPTCHA express |
|---|---|---|---|---|
| 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 express 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:
|
Medium
Integration requires you to do the following:
|
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 express with a WAF service provider or make a request from your application server to reCAPTCHA. |
| 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 score-based and checkbox keys | reCAPTCHA score-based keys | reCAPTCHA challenge page uses the optimized version of reCAPTCHA to minimize the integration. | reCAPTCHA score-based keys |
You can use one or more features of reCAPTCHA 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.
reCAPTCHA action-tokens workflow consists of the following steps:
- When an end user triggers an action protected by reCAPTCHA, the web page or the mobile application sends signals that are collected in the browser to reCAPTCHA for analysis.
- reCAPTCHA sends an action-token to the web page or the mobile application.
- You attach this action-token to the header of the request that you want to protect.
- 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.
- 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 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 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:
- The browser loads the reCAPTCHA JavaScript from reCAPTCHA.
- The reCAPTCHA JavaScript sets a session-token as a cookie on the end-user's browser after the assessment.
- 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.
- 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 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:
- At the WAF layer, the user's request is redirected to reCAPTCHA challenge page.
- reCAPTCHA responds with an HTML page embedded with the reCAPTCHA JavaScript.
- When the challenge page is rendered, reCAPTCHA assesses the user interaction. If necessary, reCAPTCHA serves a CAPTCHA challenge to the user.
Depending on the result of the assessment, reCAPTCHA does the following:
- If the user interaction passes the assessment, reCAPTCHA 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.
- If the user interaction does not pass the assessment, reCAPTCHA does not issue an exemption cookie.
reCAPTCHA 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.
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 express for WAF
You can use reCAPTCHA express to protect your applications in an environment that does not support running of reCAPTCHA JavaScript or built-in mobile SDKs, for example, IoT devices and set-top boxes. You can set up reCAPTCHA express at the WAF layer with a WAF service provider or in a standalone environment on an application server. reCAPTCHA express uses only backend signals to generate a reCAPTCHA risk score.
The reCAPTCHA WAF express workflow consists of the following steps:
- When a user requests access for a web page, the WAF service provider creates an assessment request to reCAPTCHA.
- reCAPTCHA assess the user interaction and sends a risk score.
- 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 for WAF with Google Cloud Armor on websites.
- Integrate reCAPTCHA for WAF with Google Cloud Armor on mobile applications.
- Learn about the token attributes for Fastly.
- Integrate reCAPTCHA for WAF with Fastly.
- Set up reCAPTCHA express on application servers.