Examples of reCAPTCHA firewall policies

This document shows examples of reCAPTCHA firewall policies that you can create based on the implementation of the features of reCAPTCHA WAF.

Example 1: A reCAPTCHA firewall policy with action-token

You can add a reCAPTCHA action-token to protect a user action, such as login. To ensure that the reCAPTCHA cookie is issued when the user initiates the login action, integrate the reCAPTCHA action-token script on the home page.

Create a reCAPTCHA firewall policy with the following rules:

  • The path where the rule must be applied. In this case, login.php.
  • If the action name attribute of the action-token does not match the user action that is protected or if the score is less than or equal to 0.1, then block the access.
  gcloud recaptcha firewall-policies create \
      --description="example1 policy" \
      --path="/login.php" \
      --condition="recaptcha.token.action != "login" || recaptcha.score <= 0.1" \
      --actions="block"

The following illustration shows a workflow that uses the reCAPTCHA action-token feature and the corresponding reCAPTCHA firewall policy:

Example 2: A reCAPTCHA firewall policy with session-token

You can add a reCAPTCHA session-token on pages that a user might access so that the cookie gets refreshed periodically, for example, a checkout page. Integrate the reCAPTCHA session-token script so that the reCAPTCHA cookie is issued and refreshed at the application backend before a user enters the checkout page. On the checkout page, integrate the reCAPTCHA session-token script so that the reCAPTCHA cookie is issued and refreshed at the application backend to prevent the cookie from expiring.

Create a reCAPTCHA firewall policy with the following rule:

  • The path where the rule must be applied. In this case, checkout.html.
  • If the score is less than or equal to 0.1, then block the access.
   gcloud recaptcha firewall-policies create \
       --description="example2 policy" \
       --path="/checkout.html" \
       --condition="recaptcha.score <=0.1" \
       --actions="block"

The following illustration shows a workflow that uses the reCAPTCHA session-token feature and the corresponding reCAPTCHA firewall policy:

Example 3: A reCAPTCHA firewall policy with challenge page

You can add the reCAPTCHA challenge page feature when you want the user to be redirected to an interstitial page where it determines whether the user request is potentially fraudulent or legitimate.

For the pages that you want to protect, create reCAPTCHA firewall policy rules to redirect the user to the challenge page:

  • For the protected page, if the token is not valid, then redirect the user to the challenge page. In this case, index.html.

  • If the score is less than or equal to 0.1, then redirect the user to the error page.

     gcloud recaptcha firewall-policies create \
     --description="example3-1 policy" \
     --path="/index.html" --condition="!recaptcha.token.valid" --actions="redirect"

     gcloud recaptcha firewall-policies create \
     --description="example3-2 policy" \
     --path="/index.html" --condition="recaptcha.score <= 0.1" --actions="substitute { path: /bot_error }"

The following illustration shows a workflow that uses the reCAPTCHA challenge page feature and the corresponding reCAPTCHA firewall policies:

Example 4: A reCAPTCHA firewall policy with action-token and challenge page

You can use more than one feature of reCAPTCHA WAF when you want to use different protection levels across web pages. For example, you can use the action-token or session-token feature on a page to assess the incoming traffic using the reCAPTCHA scores, and use the challenge page feature on a page where you want to ensure that the user is not a bot.

You can add a reCAPTCHA action-token to protect a user action, such as login. To ensure that the reCAPTCHA cookie is issued when the user initiates the login action, integrate the reCAPTCHA action-token script on the page before the protected login action. For example, the home page. On the download page, to redirect the user to the challenge page, use the reCAPTCHA firewall policy rule.

Create a reCAPTCHA firewall policy with the following rules:

  • The path where the rule must be applied. In this case, login.php.
  • If the action name attribute of the action-token does not match the user action that is protected or if the assessment type is not ACTION, or if the score is less than or equal to 0.1, then block the access.
  • To redirect the user to the challenge page when they want to download content, add a firewall policy rule to redirect the user.
  • If the score is less than or equal to 0.1 or if the assessment type is not CHALLENGEPAGE, then redirect the user to the error page.
    gcloud recaptcha firewall-policies create --description="example4-1 policy"
        --path="/login.php" --condition="recaptcha.token.action != "login" || recaptcha.assessment_type != AssessmentType.ACTION || recaptcha.score <= 0.1" --actions="block"

    gcloud recaptcha firewall-policies create --description="example4-2 policy"
        --path="/content/example.pdf" --condition="recaptcha.assessment_type != AssessmentType.CHALLENGEPAGE" --actions="redirect"

    gcloud recaptcha firewall-policies create --description="example4-3 policy"
        --path="/content/example.pdf" --condition="recaptcha.score <= 0.1 || recaptcha.assessment_type != AssessmentType.CHALLENGEPAGE" --actions="substitute { path: /bot_error }"

The following illustration shows a workflow that uses reCAPTCHA action-token and reCAPTCHA challenge page features, and the corresponding reCAPTCHA firewall policies:

Example 5: A reCAPTCHA firewall policy with WAF express protection and challenge page

You can add the reCAPTCHA WAF express protection feature when you want to assess the user interaction without any user friction and then redirect the users to the challenge page if the score is low. For example, to prevent data scraping, you want to block traffic to a catalog page.

Create a reCAPTCHA firewall policy with the following rule:

  • The path where the rule must be applied.
  • If the score is less than or equal to 0.3, then redirect the user to the challenge page.

The following example creates a reCAPTCHA firewall policy to redirect traffic targeting for /catalog1/itemlist.html when the score is less than 0.3.

    gcloud recaptcha firewall-policies create \
        --description="example5 policy" \
        --path="/catalog1/itemlist.html" \
        --condition="recaptcha.score <= 3" \
        --actions="redirect"

What's next