reCAPTCHA Enterprise for WAF and Google Cloud Armor integration features

reCAPTCHA Enterprise for WAF and Google Cloud Armor integration offers the following features: reCAPTCHA challenge page, reCAPTCHA action-tokens, and reCAPTCHA session-tokens. This document helps you understand these features and determine which feature best matches your use case.

Comparison of features

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

Comparison category reCAPTCHA challenge page reCAPTCHA action-tokens reCAPTCHA session-tokens
Use case 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 action-tokens to protect user actions. Use reCAPTCHA session-tokens to protect the whole user session on the site's domain.
Integration type Low

Integration requires you to configure Google Cloud Armor security policy rules.

Medium

Integration requires you to do the following:

  • Install the reCAPTCHA JavaScript on the individual pages of your site.
  • Attach the action-token to the individual request header.
  • Configure Google Cloud Armor security policy rules.
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.
Detection accuracy 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.

Highest

An action-token protects a user action.

High

A session-token protects the whole user session on the site's domain.

Supported reCAPTCHA version reCAPTCHA challenge page uses the optimized version of reCAPTCHA to minimize the integration. reCAPTCHA Enterprise score-based and checkbox site keys reCAPTCHA Enterprise score-based site keys

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. The user's request is redirected to reCAPTCHA Enterprise at the WAF layer.
  2. reCAPTCHA Enterprise responds with an HTML page embedded with the reCAPTCHA JavaScript.
  3. When the 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 3 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. Google Cloud Armor 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:

reCAPTCHA action-tokens

You can use reCAPTCHA action-tokens to protect important user interactions, such as checkout.

In this feature, you install the reCAPTCHA Enterprise site keys on your web pages. When there is a user interaction, reCAPTCHA Enterprise sends an encrypted response, called the action-token, to the end-user's browser. You attach this action-token to a predefined request header wherever you need to protect any user action. Google Cloud Armor decodes and validates the action-token attributes instead of your backend application. You can configure security policy rules based on various attributes from the action-token, without requiring token assessment from your backend application.

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

reCAPTCHA action-tokens attributes

The following table lists the set of attributes for reCAPTCHA action-tokens:

Attribute name Data type Description
score float The score from a reCAPTCHA token. A valid score ranges from 0.0 to 1.0. The score 1.0 indicates that the interaction poses low risk and is likely legitimate, whereas 0.0 indicates that the interaction poses high risk and might be fraudulent. For more information, see Interpreting scores.
captcha_status string The CAPTCHA status from a reCAPTCHA token. Following are the three possible statuses:
  • Challenges were not involved when assessing the user.
  • Challenges were involved, and the user solved them correctly.
  • Challenges were involved, and the user failed to solve them.
action_name string The action_name is the action parameter that you specified for a user interaction when calling grecaptcha.enterprise.execute(). For more information, see Action names.

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 the load on reCAPTCHA Enterprise.

In this feature, the reCAPTCHA JavaScript sets a session-token as a cookie on the end-user's browser after the assessment. The end user's browser attaches the cookie and refreshes the cookie as long as the reCAPTCHA JavaScript remains active. Google Cloud Armor validates this cookie and applies actions based on the security policy rules.

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.

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

reCAPTCHA session-tokens attributes

The following table lists the attributes for reCAPTCHA session-tokens:

Attribute name Data type Description
Score float The score from a reCAPTCHA token. A valid score ranges from 0.0 to 1.0. The score 1.0 indicates that the interaction poses low risk and is likely legitimate, whereas 0.0 indicates that the interaction poses high risk and might be fraudulent. For more information, see Interpreting scores.

What's next

  • Learn about how to implement the features of the reCAPTCHA Enterprise for WAF and Google Cloud Armor integration.