Integrate reCAPTCHA for WAF with Akamai

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 for WAF with Akamai.

To complete the integration, you must implement one or more features of reCAPTCHA for WAF, create reCAPTCHA firewall policies, and integrate with Akamai by creating and configuring Akamai EdgeWorkers service.

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 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. For Akamai configuration, ensure that you have the following:

   1. An Akamai account and an Akamai property for your application.

   2. Access to the Akamai EdgeWorkers from the Akamai Marketplace.

   3. Ability to create EdgeWorkers.

7. Download the reCAPTCHA package for Akamai recaptcha_akamai_client_0.0.2.tgz.

Implement features of reCAPTCHA for WAF

Depending on your requirements, you can use one or more features of reCAPTCHA 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 running on your web pages to generate action-tokens. After reCAPTCHA 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 Akamai 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 akamai for Akamai.

   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 akamai for Akamai.

   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": "akamai",
   
     "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, 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.

To learn about how to install session-token keys on your web pages, see Integrate score-based keys with the frontend.

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 refreshes the session-token periodically to prevent it from expiring.

Install session-tokens on each page that needs to be protected by reCAPTCHA. We recommend that you protect every page with reCAPTCHA 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 akamai for Akamai.

   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 akamai for Akamai.

   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": "akamai",
   
     "wafFeature": "SESSION_TOKEN"
   
   
   }
   }
   
   

   Record your session-token key for later use.

   If you want to inject the reCAPTCHA JavaScript from Akamai, skip the next step and configure the properties in Akamai Property Manager.

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 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 akamai for Akamai.

   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 akamai for Akamai.

   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": "akamai",
   
     "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.
   • WAF_SERVICE: Name of the WAF service provider. Specify akamai for Akamai.

   Execute the gcloud recaptcha keys create command:

   Linux, macOS, or Cloud Shell

   gcloud recaptcha keys create \
   --express \
   --display-name=DISPLAY_NAME  \
   --waf-service=WAF_SERVICE
   

   Windows (PowerShell)

   gcloud recaptcha keys create `
   --express `
   --display-name=DISPLAY_NAME  `
   --waf-service=WAF_SERVICE
   

   Windows (cmd.exe)

   gcloud recaptcha keys create ^
   --express ^
   --display-name=DISPLAY_NAME  ^
   --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.
   • WAF_SERVICE: Name of the WAF service provider. Specify akamai for Akamai.

   HTTP method and URL:

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

   Request JSON body:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
     
   }
   

   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,
   
   },
   "wafSettings": {
     "wafService": "akamai",
   
     
   
   }
   }
   
   

   Record your express key for later use.

Integrate with Akamai

To integrate with Akamai, you must set up the EdgeWorker service and configure properties for the EdgeWorker service in Property Manager.

Set up the EdgeWorker service

1. From the Akamai Control Center, create an EdgeWorker ID and assign the Editor role to the EdgeWorker ID that you create.

2. To upload the reCAPTCHA package for Akamai, create an EdgeWorker version by using the reCAPTCHA package that you downloaded.

3. Activate the EdgeWorker version.

Configure properties in Property Manager

1. Launch Property Manager.

2. Select your Akamai property that you want to protect, and create a new version of the property.

3. Depending on the WAF features that you have implemented, create your global user-defined variables. The global variables you set in properties start with the PMUSER_ prefix.

   The following table lists the variables that you can create and add in the property variables section:

   Variable name	Description	Security setting
   RECAPTCHAJSINSTALL	Inject reCAPTCHA JavaScript. URLs of the pages where you want Akamai 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.	Hidden
   RECAPTCHACHALLENGESITEKEY	reCAPTCHA challenge-page key. This variable is required if you want to redirect users to the reCAPTCHA challenge page.	Hidden
   RECAPTCHAACTIONSITEKEY	reCAPTCHA action-token key. This variable is required if you're using reCAPTCHA action-token for protecting your pages.	Hidden
   RECAPTCHASESSIONSITEKEY	reCAPTCHA session-token key. This variable is required if you are using reCAPTCHA session-token for protecting your pages. You need to use this variable if RECAPTCHAJSINSTALL is set to configure reCAPTCHA JavaScript from Akamai.	Hidden
   RECAPTCHAEXPRESSSITEKEY	reCAPTCHA express key. This variable is required if you're using reCAPTCHA express for protecting your pages.	Hidden
   GCPPROJECTNUMBER	Your Google Cloud project ID.	Hidden
   GCPAPIKEY	The API key that you created for authentication.	Hidden

   For instructions, see Create a variable.

4. To enable the EdgeWorker service, add a rule using the Blank Rule Template with the following information:

   • Criteria

     • Name: reCAPTCHA EdgeWorkers rule

     • Criteria: Match All
       If
       Path
       matches one of
       /*

       The matches one of criteria must match a superset of the URLs that need to be protected by reCAPTCHA. The path /* includes all the paths. You can choose to add specific pages.

     • Optional: If you want to add an additional condition to limit the file extensions, use the following:

       If
       File Extension
       is one of
       html

   • Behavior

     • Enable: On
     • Identifier: Your_EdgeWorker_ID
     • Enable mPulse reports: Off

5. To forward the call from the EdgeWorker service to the reCAPTCHA createAssessment API, add a new rule using the Blank Rule Template with the following information:

   • Criteria

     • Name: reCAPTCHA assessment rule
     • Criteria: Match All
       If
       Path
       matches one of
       /v1/projects/*/assessments

   • Behavior

     • Origin Type: Your Origin
     • Origin Server Hostname: public-preview-recaptchaenterprise.googleapis.com
     • Forward Host Header: Custom Value
     • Custom Forward Host Header: public-preview-recaptchaenterprise.googleapis.com
     • Cache Key Hostname: Origin Hostname
     • Supports Gzip Compression: Yes
     • Send True Client IP Header: Yes
     • True Client IP Header Name: True-Client-IP
     • Allow Clients To Set True Client IP Header: No
     • Verification Settings: Use platform settings
     • Use SNI TLS Extension: Yes
     • HTTP Port: 80
     • HTTPS Port: 443

6. Optional: To forward the call from the EdgeWorker service to the reCAPTCHA challenge page, add a new rule to redirect traffic to the challenge page with the following information:

   • Criteria

     • Name: reCAPTCHA challenge page rule
     • Criteria: Match All
       If
       Path
       matches one of
       /recaptcha/challengepage

   • Behavior

     • Origin Type: Your Origin
     • Origin Server Hostname: www.google.com
     • Forward Host Header: Custom Value
     • Custom Forward Host Header: www.google.com
     • Cache Key Hostname: Origin Hostname
     • Supports Gzip Compression: Yes
     • Send True Client IP Header: Yes
     • True Client IP Header Name: True-Client-IP
     • Allow Clients To Set True Client IP Header: No
     • Verification Settings: Use platform settings
     • Use SNI TLS Extension: Yes
     • HTTP Port: 80
     • HTTPS Port: 443

7. Activate the changes:

   1. Activate the changes on staging.
   2. Test the changes on staging.
   3. Activate the changes on production.

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

• Manage firewall policies.