Integrate with Google Cloud Armor for websites

This document shows you how to integrate reCAPTCHA Enterprise for WAF with Google Cloud Armor on websites.

To complete the integration, you must implement one or more features of reCAPTCHA Enterprise for WAF and configure Google Cloud Armor security policies.

Before you begin

1. Enable the reCAPTCHA Enterprise API.

   Enable the API

2. 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 and the type of WAF feature that you want to implement on those pages.

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.

Implement reCAPTCHA action-tokens

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 Google Cloud Armor can evaluate the token attributes.

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

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

   Console

   1. In the Google Cloud console, go to the reCAPTCHA Enterprise page.

      Go to reCAPTCHA Enterprise

   2. Verify that the name of your project appears in the resource selector at the top of the page.

      If you don't see the name of your project, click the resource selector, then select your project.

   3. Click Create key.

      
   4. In the Display name field, enter a display name for the key.
   5. Depending on the platform for which you want to create reCAPTCHA keys for WAF, perform the appropriate action:

   1. From the Choose platform type menu, select Website.

      

      The Domain list section appears.

   2. Enter the domain name for your website:

      1. In the Domain list section, click Add a domain.

         
      2. In the Domain field, enter the name of your domain.

      3. Optional: To add an additional domain, click Add a domain and enter the name of another domain in the Domain field. You can add up to a maximum of 250 domains.

         For websites, the reCAPTCHA key is unique to the domains and subdomains that you specify. You can specify more than one domain if you serve your website from multiple domains. If you specify a domain (for example, examplepetstore.com), you do not need to specify its subdomains (for example, subdomain.examplepetstore.com).

         To use a key on more than 250 domains, click the Disable domain verification toggle. reCAPTCHA Enterprise will then ignore the Domain list. You need to perform domain verification yourself by examining the tokenProperties.hostname field in the assessments you create.

   3. Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge section.
      
   4. Turn on the Web application firewall (WAF) toggle.
      Note: By default, reCAPTCHA keys for WAF are created for Google Cloud Armor. If you want to create reCAPTCHA keys for other WAF service provider, contact our sales team to enable your WAF service provider.
      
      

   5. From the Feature menu, select Action token.

      

   6. Optional: Turn on Use checkbox challenge.

   7. Click Create key.

   The newly created key is listed on the reCAPTCHA keys page.

   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 CA for Google Cloud Armor.

   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 CA for Google Cloud Armor.

   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": "CA",
     "wafFeature": "ACTION_TOKEN"
     
   }
   }
   
   

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>
     
     

Implement reCAPTCHA session-tokens

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 satisfy the following requirements:

• The web page must be the page 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.
• The web page is protected by a Google Cloud Armor security policy.

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.

   Console

   1. In the Google Cloud console, go to the reCAPTCHA Enterprise page.

      Go to reCAPTCHA Enterprise

   2. Verify that the name of your project appears in the resource selector at the top of the page.

      If you don't see the name of your project, click the resource selector, then select your project.

   3. Click Create key.

      
   4. In the Display name field, enter a display name for the key.
   5. Depending on the platform for which you want to create reCAPTCHA keys for WAF, perform the appropriate action:

   1. From the Choose platform type menu, select Website.

      

      The Domain list section appears.

   2. Enter the domain name for your website:

      1. In the Domain list section, click Add a domain.

         
      2. In the Domain field, enter the name of your domain.

      3. Optional: To add an additional domain, click Add a domain and enter the name of another domain in the Domain field. You can add up to a maximum of 250 domains.

         For websites, the reCAPTCHA key is unique to the domains and subdomains that you specify. You can specify more than one domain if you serve your website from multiple domains. If you specify a domain (for example, examplepetstore.com), you do not need to specify its subdomains (for example, subdomain.examplepetstore.com).

         To use a key on more than 250 domains, click the Disable domain verification toggle. reCAPTCHA Enterprise will then ignore the Domain list. You need to perform domain verification yourself by examining the tokenProperties.hostname field in the assessments you create.

   3. Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge section.
      
   4. Turn on the Web application firewall (WAF) toggle.
      Note: By default, reCAPTCHA keys for WAF are created for Google Cloud Armor. If you want to create reCAPTCHA keys for other WAF service provider, contact our sales team to enable your WAF service provider.
      
      

   5. From the Feature menu, select Session token.

      
   6. Optional:Turn on 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.

   7. Click Create key.

   The newly created key is listed on the reCAPTCHA keys page.

   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 CA for Google Cloud Armor.

   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 CA for Google Cloud Armor.

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

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>
   
   
   

Implement a reCAPTCHA 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, create a challenge-page key for your website.

Console

1. In the Google Cloud console, go to the reCAPTCHA Enterprise page.

   Go to reCAPTCHA Enterprise

2. Verify that the name of your project appears in the resource selector at the top of the page.

   If you don't see the name of your project, click the resource selector, then select your project.

3. Click Create key.

   
4. In the Display name field, enter a display name for the key.
5. Depending on the platform for which you want to create reCAPTCHA keys for WAF, perform the appropriate action:

1. From the Choose platform type menu, select Website.

   
2. Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge section.
   
3. Turn on the Web application firewall (WAF) toggle.
   Note: By default, reCAPTCHA keys for WAF are created for Google Cloud Armor. If you want to create reCAPTCHA keys for other WAF service provider, contact our sales team to enable your WAF service provider.
   
   

4. From the Feature menu, select Challenge page.

   
5. Turn on Disable domain verification.

   When you disable domain verification for challenge-page keys, Google Cloud Armor verifies the domain.

6. Click Create key.

The newly created key is listed on the reCAPTCHA keys page.

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 CA for Google Cloud Armor.

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 CA for Google Cloud Armor.

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": "CA",
  "wafFeature": "CHALLENGE_PAGE"
  
}
}

Important: You shouldn't delete the challenge-page key while it is being used in a security policy. If the challenge-page key is not available when the reCAPTCHA challenge page is rendered, the reCAPTCHA challenge page shows an error and users cannot pass the assessment. Therefore, you must disassociate the key from the security policy before deleting it. For details, see Configure rules for bot management.

Configure Google Cloud Armor security policies

After implementing the features of reCAPTCHA Enterprise for WAF, you must configure Google Cloud Armor security policies for bot management.

If you implemented a reCAPTCHA challenge page, then you must do the following:

1. Associate the challenge-page key with your security policy.
2. Configure a security policy rule to redirect a request for reCAPTCHA Enterprise assessment.

If you implemented reCAPTCHA action tokens or session tokens, then you must configure a security policy rule that evaluates reCAPTCHA Enterprise tokens.

Before configuring the Google Cloud Armor security policies, understand the reCAPTCHA token attributes for Google Cloud Armor.

To learn how to configure Google Cloud Armor security policies and use the reCAPTCHA keys for WAF with your security policies, see Configure rules for bot management.

What's next

• Examples of integration with Google Cloud Armor.
• Learn how to implement reCAPTCHA WAF features with Google Cloud Armor.