Integrate reCAPTCHA Enterprise for WAF with Cloudflare

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.

This document shows you how to integrate reCAPTCHA Enterprise for WAF with Cloudflare.

To complete the integration, you must implement one or more features of reCAPTCHA Enterprise for WAF, create reCAPTCHA firewall policies, and integrate with Cloudflare by deploying and configuring a Cloudflare Worker serverless application.

Before you begin

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

   Record your Google Cloud project ID for later use.

2. Make sure that billing is enabled for your Google Cloud project.

   Note: Free trials are not billed.

3. Enable the reCAPTCHA Enterprise API.

   Enable the API

4. Create an API key for authentication:

   1. In the Google Cloud console, go to the Credentials page.

      Go to Credentials

   2. Click Create credentials, and then select API key.
   3. Record the API key for later use.

5. Plan how you want to implement the features of reCAPTCHA Enterprise for WAF to protect your website.

   1. Choose one or more WAF features that best match your use case.
   2. Identify the pages that you want to protect.
   3. Choose the type of WAF features that you want to implement on the identified pages.
   4. Identify the conditions to manage user access.
   5. Understand the reCAPTCHA firewall policy components and their attributes that help you to create reCAPTCHA firewall policies. For examples, see Examples of reCAPTCHA firewall policies.

6. Create or choose a Cloudflare account with Cloudflare Worker capabilities.

7. Create or choose a Cloudflare website.

8. Download the reCAPTCHA package for Cloudflare recaptcha_cloudflare_client_0.0.2.tar.gz.

Implement features of reCAPTCHA Enterprise for WAF

Depending on your requirements, you can use one or more features of reCAPTCHA Enterprise for WAF in a single application.

If you want to use more than one feature, then you must create a reCAPTCHA key for each of those features and use them in your application. For example, if you want to use reCAPTCHA action-tokens and reCAPTCHA challenge page, then you must create an action-token key and a challenge-page key, and use them in your application.

action-token

You must have reCAPTCHA Enterprise running on your web pages to generate action-tokens. After reCAPTCHA Enterprise generates an action-token, you attach the action-token to a predefined request header wherever you need to protect any user action, such as checkout. By default, action-tokens are valid for 30 minutes, but can vary depending on the traffic. You must attach the action-token to a predefined request header before the token expires, so that the cloudflare can evaluate the token attributes.

To implement a reCAPTCHA action-token, do the following:

1. Create an action-token key for your website.

   gcloud

   To create reCAPTCHA keys, use the gcloud recaptcha keys create command.

   Before using any of the command data below, make the following replacements:

   • DISPLAY_NAME: Name for the key. Typically a site name.
   • INTEGRATION_TYPE: Type of integration. Specify score or checkbox.
   • DOMAIN_NAME: Domains or subdomains of websites allowed to use the key.

     Specify multiple domains as a comma-separated list. Optional: Specify --allow-all-domains to disable domain verification.

     Disabling domain verification is a security risk because there are no restrictions on the site, so your reCAPTCHA key can be accessed and used by anyone.

   • WAF_FEATURE: Name of the WAF feature. Specify action-token.
   • WAF_SERVICE: Name of the WAF service provider. Specify cloudflare for cloudflare.

   Execute the gcloud recaptcha keys create command:

   Linux, macOS, or Cloud Shell

   
   gcloud recaptcha keys create \
   --web \
   --display-name=DISPLAY_NAME  \
   --integration-type=INTEGRATION_TYPE \
   --domains=DOMAIN_NAME \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE
   
   

   Windows (PowerShell)

   
   gcloud recaptcha keys create `
   --web `
   --display-name=DISPLAY_NAME  `
   --integration-type=INTEGRATION_TYPE `
   --domains=DOMAIN_NAME `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE
   
   

   Windows (cmd.exe)

   
   gcloud recaptcha keys create ^
   --web ^
   --display-name=DISPLAY_NAME  ^
   --integration-type=INTEGRATION_TYPE ^
   --domains=DOMAIN_NAME ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE
   
   

   The response contains the newly created reCAPTCHA key.

   REST

   For API reference information about key types and integration types, see Key and Integration type.

   Before using any of the request data, make the following replacements:

   • DISPLAY_NAME: Name for the key. Typically a site name.
   • INTEGRATION_TYPE: Type of integration. Specify score or checkbox.
   • DOMAIN_NAME: Domains or subdomains of websites allowed to use the key.

     Specify multiple domains as a comma-separated list. Optional: Specify --allow-all-domains to disable domain verification.

     Disabling domain verification is a security risk because there are no restrictions on the site, so your reCAPTCHA key can be accessed and used by anyone.

   • WAF_FEATURE: Name of the WAF feature. Specify action-token.
   • WAF_SERVICE: Name of the WAF service provider. Specify cloudflare for cloudflare.

   HTTP method and URL:

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

   Request JSON body:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
   "wafFeature": "WAF_FEATURE"
     }
     "webSettings": {
       "allowedDomains": "DOMAINS",
       "integrationType": "TYPE_OF_INTEGRATION"
      }
   }
   

   To send your request, choose one of these options:

   curl

   Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

   Save the request body in a file named request.json, and execute the following command:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

   PowerShell

   Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

   Save the request body in a file named request.json, and execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

   
   {
     "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
    "integrationType": "SCORE",
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
     "wafFeature": "ACTION_TOKEN"
     
   }
   }
   
   

   Record your action-token key for later use.

2. Integrate reCAPTCHA JavaScript on your web pages with the action-token key that you created. For instructions, refer to the document that corresponds with the integration type of your action-token key.
   • For the SCORE integration type, see Integrate score-based keys with the frontend.
   • For the CHECKBOX integration type, see Render the reCAPTCHA widget on the frontend.
3. After you receive the token from reCAPTCHA Enterprise, attach the token to a predefined request header in the following format:

    X-Recaptcha-Token: value-of-your-action-token
   

   You can use languages such as XHR, Ajax, or Fetch API to attach the token to a predefined request header.

   The following sample script shows how to protect the execute action and attach the token to a predefined request header using JavaScript + XHR:

     
     <script>
       src="https://www.google.com/recaptcha/enterprise.js?render=ACTION_TOKEN_KEY"></script>
   
       <script>
       function onSuccess(action_token) {
            const xhr = new XMLHttpRequest();
            xhr.open('GET','YOUR_URL', false);
            // Attach the action-token to the predefined request header
            xhr.setRequestHeader("X-Recaptcha-Token", action_token);
            xhr.send(null);
          }
          function onError(reason) {
            alert('Response promise rejected: ' + reason);
          grecaptcha.enterprise.ready(function () {
            document.getElementById("execute-button").onclick = () => {
              grecaptcha.enterprise.execute('ACTION_TOKEN_KEY', {
              }).then(onSuccess, onError);
            };
          });
         }
       </script>
     
     

session-token

The reCAPTCHA JavaScript sets a reCAPTCHA 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.

To provide a session-token as a cookie, install a session-token key on at least one of your web pages that the end user browses before the page that needs to be protected. For example, if you want to protect the checkout page, install a session-token key on the home page or product page.

You can either include the reCAPTCHA JavaScript on your web pages by configuring the wrangler.toml file when installing the reCAPTCHA package for Cloudflare or install the session-key on your web pages. Including the reCAPTCHA JavaScript from Cloudflare integrates reCAPTCHA Enterprise using the session-token key without the need for manual installation of the keys on your web pages.

You can use this cookie to protect the end user's subsequent requests and page loads on a specific domain. Session-tokens are valid for 30 minutes by default. However, if the end user stays on the page where you implemented the session-token, reCAPTCHA Enterprise refreshes the session-token periodically to prevent it from expiring.

Install session-tokens on each page that needs to be protected by reCAPTCHA Enterprise. We recommend that you protect every page with reCAPTCHA Enterprise and use Google Cloud Armor rules to enforce access on all the pages, except the first page that end users browse.

The following is a sample reCAPTCHA session-token:

   recaptcha-ca-t=value-of-your-session-token;domain=domain;expires=expiration_time

To implement a reCAPTCHA session-token, do the following:

1. Create a session-token key for your website.

   gcloud

   To create reCAPTCHA keys, use the gcloud recaptcha keys create command.

   Before using any of the command data below, make the following replacements:

   • DISPLAY_NAME: Name for the key. Typically a site name.
   • INTEGRATION_TYPE: Type of integration. Specify score.
   • DOMAIN_NAME: Domains or subdomains of websites allowed to use the key.

     Specify multiple domains as a comma-separated list. Optional: Specify --allow-all-domains to disable domain verification.

     Disabling domain verification is a security risk because there are no restrictions on the site, so your reCAPTCHA key can be accessed and used by anyone.

   • WAF_FEATURE: Name of the WAF feature. Specify session-token.
   • WAF_SERVICE: Name of the WAF service provider. Specify cloudflare for cloudflare.

   Execute the gcloud recaptcha keys create command:

   Linux, macOS, or Cloud Shell

   
   gcloud recaptcha keys create \
   --web \
   --display-name=DISPLAY_NAME  \
   --integration-type=INTEGRATION_TYPE \
   --domains=DOMAIN_NAME \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE
   
   

   Windows (PowerShell)

   
   gcloud recaptcha keys create `
   --web `
   --display-name=DISPLAY_NAME  `
   --integration-type=INTEGRATION_TYPE `
   --domains=DOMAIN_NAME `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE
   
   

   Windows (cmd.exe)

   
   gcloud recaptcha keys create ^
   --web ^
   --display-name=DISPLAY_NAME  ^
   --integration-type=INTEGRATION_TYPE ^
   --domains=DOMAIN_NAME ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE
   
   

   The response contains the newly created reCAPTCHA key.

   REST

   For API reference information about key types and integration types, see Key and Integration type.

   Before using any of the request data, make the following replacements:

   • DISPLAY_NAME: Name for the key. Typically a site name.
   • INTEGRATION_TYPE: Type of integration. Specify score.
   • DOMAIN_NAME: Domains or subdomains of websites allowed to use the key.

     Specify multiple domains as a comma-separated list. Optional: Specify --allow-all-domains to disable domain verification.

     Disabling domain verification is a security risk because there are no restrictions on the site, so your reCAPTCHA key can be accessed and used by anyone.

   • WAF_FEATURE: Name of the WAF feature. Specify session-token.
   • WAF_SERVICE: Name of the WAF service provider. Specify cloudflare for cloudflare.

   HTTP method and URL:

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

   Request JSON body:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
   "wafFeature": "WAF_FEATURE"
     }
     "webSettings": {
       "allowedDomains": "DOMAINS",
       "integrationType": "TYPE_OF_INTEGRATION"
      }
   }
   

   To send your request, choose one of these options:

   curl

   Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

   Save the request body in a file named request.json, and execute the following command:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

   PowerShell

   Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

   Save the request body in a file named request.json, and execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

   
   {
     "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
    "integrationType": "SCORE",
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
     "wafFeature": "SESSION_TOKEN"
     
   }
   }
   
   

   Record your session-token key for later use.

   If you want to inject the reCAPTCHA JavaScript from Cloudflare, skip the next step and configure wranger.toml.

2. Add the session-token key and waf=session to the reCAPTCHA JavaScript.

   The following sample script shows how to implement a session-token on a web page:

   
   <!DOCTYPE html>
   <html lang="en">
   <head>
    <meta charset="UTF-8">
    <title>reCAPTCHA WAF Session Token</title>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=SESSION_TOKEN_KEY&waf=session" async defer></script>
    <body></body>
   </head>
   </html>
   
   
   

challenge-page

When you implement a reCAPTCHA challenge page, reCAPTCHA Enterprise redirects to an interstitial page where it determines if it's necessary to show a CAPTCHA challenge to a user. Therefore, CAPTCHA challenges might not be visible to all users.

To implement a reCAPTCHA challenge page, do the following:

1. Create a challenge-page key for your website.

   gcloud

   To create reCAPTCHA keys, use the gcloud recaptcha keys create command.

   Before using any of the command data below, make the following replacements:

   • DISPLAY_NAME: Name for the key. Typically a site name.
   • INTEGRATION_TYPE: Type of integration. Specify invisible.
   • DOMAIN_NAME: Domains or subdomains of websites allowed to use the key. Specify --allow-all-domains.
   • WAF_FEATURE: Name of the WAF feature. Specify challenge-page.
   • WAF_SERVICE: Name of the WAF service provider. Specify cloudflare for cloudflare.

   Execute the gcloud recaptcha keys create command:

   Linux, macOS, or Cloud Shell

   
   gcloud recaptcha keys create \
   --web \
   --display-name=DISPLAY_NAME  \
   --integration-type=INTEGRATION_TYPE \
   --domains=DOMAIN_NAME \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE
   
   

   Windows (PowerShell)

   
   gcloud recaptcha keys create `
   --web `
   --display-name=DISPLAY_NAME  `
   --integration-type=INTEGRATION_TYPE `
   --domains=DOMAIN_NAME `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE
   
   

   Windows (cmd.exe)

   
   gcloud recaptcha keys create ^
   --web ^
   --display-name=DISPLAY_NAME  ^
   --integration-type=INTEGRATION_TYPE ^
   --domains=DOMAIN_NAME ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE
   
   

   The response contains the newly created reCAPTCHA key.

   REST

   For API reference information about key types and integration types, see Key and Integration type.

   Before using any of the request data, make the following replacements:

   • DISPLAY_NAME: Name for the key. Typically a site name.
   • INTEGRATION_TYPE: Type of integration. Specify invisible.
   • DOMAIN_NAME: Domains or subdomains of websites allowed to use the key. Specify --allow-all-domains.
   • WAF_FEATURE: Name of the WAF feature. Specify challenge-page.
   • WAF_SERVICE: Name of the WAF service provider. Specify cloudflare for cloudflare.

   HTTP method and URL:

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

   Request JSON body:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
   "wafFeature": "WAF_FEATURE"
     }
     "webSettings": {
       "allowedDomains": "DOMAINS",
       "integrationType": "TYPE_OF_INTEGRATION"
      }
   }
   

   To send your request, choose one of these options:

   curl

   Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

   Save the request body in a file named request.json, and execute the following command:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

   PowerShell

   Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

   Save the request body in a file named request.json, and execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

   
   {
     "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
     "integrationType": "INVISIBLE",
    
   },
   "wafSettings": {
     "wafService": "cloudflare",
     "wafFeature": "CHALLENGE_PAGE"
     
   }
   }
   
   

   Record your challenge-page key for later use.

2. To redirect users to the reCAPTCHA challenge page and receive a reCAPTCHA token, create a firewall policy with the redirect action on protected pages.

express

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.

To implement reCAPTCHA WAF express protection, create an express key.

1. 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.

2. gcloud

   To create reCAPTCHA keys, use the gcloud recaptcha keys create command.

   Before using any of the command data below, make the following replacements:

   • DISPLAY_NAME: Name for the key. Typically a site name.
   • INTEGRATION_TYPE: Type of integration. Specify score.
   • DOMAIN_NAME: Domains or subdomains of websites allowed to use the key. Specify --allow-all-domains.
   • WAF_FEATURE: Name of the WAF feature. Specify express.
   • WAF_SERVICE: Name of the WAF service provider.

   Execute the gcloud recaptcha keys create command:

   Linux, macOS, or Cloud Shell

   
   gcloud recaptcha keys create \
   --web \
   --display-name=DISPLAY_NAME  \
   --integration-type=INTEGRATION_TYPE \
   --domains=DOMAIN_NAME \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE
   
   

   Windows (PowerShell)

   
   gcloud recaptcha keys create `
   --web `
   --display-name=DISPLAY_NAME  `
   --integration-type=INTEGRATION_TYPE `
   --domains=DOMAIN_NAME `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE
   
   

   Windows (cmd.exe)

   
   gcloud recaptcha keys create ^
   --web ^
   --display-name=DISPLAY_NAME  ^
   --integration-type=INTEGRATION_TYPE ^
   --domains=DOMAIN_NAME ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE
   
   

   The response contains the newly created reCAPTCHA key.

   REST

   For API reference information about key types and integration types, see Key and Integration type.

   Before using any of the request data, make the following replacements:

   • DISPLAY_NAME: Name for the key. Typically a site name.
   • INTEGRATION_TYPE: Type of integration. Specify score.
   • DOMAIN_NAME: Domains or subdomains of websites allowed to use the key. Specify --allow-all-domains.
   • WAF_FEATURE: Name of the WAF feature. Specify express.
   • WAF_SERVICE: Name of the WAF service provider.

   HTTP method and URL:

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

   Request JSON body:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
   "wafFeature": "WAF_FEATURE"
     }
     "webSettings": {
       "allowedDomains": "DOMAINS",
       "integrationType": "TYPE_OF_INTEGRATION"
      }
   }
   

   To send your request, choose one of these options:

   curl

   Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

   Save the request body in a file named request.json, and execute the following command:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

   PowerShell

   Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

   Save the request body in a file named request.json, and execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

   
   {
     "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
    "integrationType": "SCORE",
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
     "wafFeature": "EXPRESS"
   
   }
   }
   
   

   Record your express key for later use.

Integrate with Cloudflare

To use the reCAPTCHA firewall policies, you must deploy and configure a Cloudflare Worker serverless application.

Before you begin the integration process, do the following:

1. Create a CLOUDFLARE_API_TOKEN, and choose the Edit Cloudflare Workers template. Record the API token for later use.

2. Get your Cloudflare API account ID and record it for later use.

Install the reCAPTCHA package for Cloudflare

1. Download and install the reCAPTCHA package for Cloudflare:

   1. 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.

   2. Install the wrangler package:

       npm install -g wrangler
      

   3. Download the reCAPTCHA package for Cloudflare:

      wget --load-cookies /tmp/cookies.txt https://dl.google.com/recaptchaenterprise/cloudflare_client/releases/recaptcha_cloudflare_client_0.0.2.tar.gz -O recaptcha_cloudflare_client_0.0.2.tar.gz && rm -rf /tmp/cookies.txt
      

   4. Unpack the reCAPTCHA package for Cloudflare:

      tar -xvzf recaptcha_cloudflare_client_0.0.2.tar.gz
      

2. In the wrangler.toml file, configure the following variables in the vars section:

   • GCP_API_KEY: the Google Cloud API key that you created for authentication.
   • GCP_PROJECT_NUMBER: your Google Cloud project number.
   • RECAPTCHA_EXPRESS_SITE_KEY: the express key if you are using the reCAPTCHA WAF express protection.
   • RECAPTCHA_SESSION_SITE_KEY: the session-token key if you are using reCAPTCHA session-token.
   • RECAPTCHA_ACTION_SITE_KEY: the action-token key if you are using reCAPTCHA action-token.
   • RECAPTCHA_CHALLENGE_SITE_KEY: the challenge-page key if you are using reCAPTCHA challenge page.
   • RECAPTCHA_JS_INSTALL: URLs of the pages where you want Cloudflare worker to install the reCAPTCHA JavaScript using the session-token key. Specify the paths as a glob pattern and use ; as the delimiter. This option is available only for reCAPTCHA session-token.

   • RECAPTCHA_ASSESSMENT_CALL: URLs of the pages where you want Cloudflare worker to call the reCAPTCHA API to assess the reCAPTCHA score and perform the action that is configured in the firewall policy. Specify the paths as a glob pattern and use ; as the delimiter.

     Note: The path that you specify in this variable must match the path that is specified in the rule of the firewall policy.

3. Deploy the application:

   wrangler deploy
   

Configure Cloudflare routes to the Worker application

1. Sign in to the Cloudflare dashboard and select your account.
2. In the navigation menu, click Workers & Pages, and then select your Worker application.
3. Click the Triggers tab, and then click Add route.
4. In the Add route dialog, enter the path of your web page that needs to be protected by reCAPTCHA Enterprise, select the appropriate zone, and click Add route.

Create reCAPTCHA firewall policies

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 Enterprise 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 Enterprise 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

• Manage firewall policies.