Create reCAPTCHA firewall policies rules

This document shows you how to create reCAPTCHA firewall policy rules.

Before you begin

You must create a firewall policy that specifies rules for every page that you want to protect on your website. You can create firewall policies with one or more features of reCAPTCHA for WAF.

In your reCAPTCHA firewall policy, add rules in the order of the intended priority. The first rule has the highest order. You can also reorder the priority by using ReorderFirewallPoliciesRequest. For an incoming request, when a policy condition matches for the specified path, your WAF service provider implements the defined action and the subsequent rules are not evaluated.

  1. Based on the features that you chose, do the following:
    • Identify the path you want to protect.
    • Identify the conditions to allow, redirect, or block access.
    • Prioritize the rules.
  2. Understand the firewall policy components and their attributes.

  3. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  4. To override gcloud CLI to access the public preview version of the reCAPTCHA API, run the following command: 
        gcloud config set api_endpoint_overrides/recaptchaenterprise https://public-preview-recaptchaenterprise.googleapis.com/
  5. To create reCAPTCHA firewall policies, use the gcloud recaptcha firewall-policies create command:

    In your reCAPTCHA firewall policy, add rules in order of the intended priority. You must add a rule with the highest priority first. For an incoming request, when a policy condition matches for the specified path, your WAF service provider implements the defined action and the subsequent rules are not evaluated. The default rule is to allow access.

       gcloud recaptcha firewall-policies create \
      --actions=ACTION \
      --condition=CONDITION \
      --description=DESCRIPTION \
      --path=PATH

    Provide the following values:

    • ACTION: The actions that your WAF service provider must take for the incoming request. It can contain at most one terminal action, which is an action that forces a response. Specify one of the following actions:
      • allow: allows access to the requested page. This is a terminal action.
      • block: denies access to the requested page. This is a terminal action.
      • redirect: redirects the incoming user request to the reCAPTCHA challenge page. This is a terminal action.
      • substitute: serves a different page other than the requested page to a fraudulent user request. This is a terminal action.
      • set_header: sets a custom header and allows the incoming user request to continue to the backend. The backend then can trigger a customized protection. This is a non-terminal action.
    • CONDITION: a CEL (Common Expression Language) conditional expression that specifies if the reCAPTCHA firewall policy applies to an incoming user request. If this condition evaluates to true and the requested path matches the path pattern, the associated actions are executed by the WAF service provider. The condition string is checked for CEL syntax correctness on creation. For more information about the language definition, CEL language definition.
    • DESCRIPTION: a description of what the reCAPTCHA firewall policy aims to achieve. The description must be at most 256 UTF-8 characters.
    • PATH: the path for which the reCAPTCHA firewall policy applies. It must be specified as a glob pattern. For more information on glob, see the manual page.

    After the successful execution of the command, output similar to the following is displayed:

         Created [100].

    The following example creates a reCAPTCHA firewall policy to block traffic targeting for /example/page.html when the score is less than 0.1.

       gcloud recaptcha firewall-policies create \
     --description="example policy" \
     --path="/example/page.html" \
     --condition="recaptcha.score < 0.1" \
     --actions="block"

What's next