Implement the reCAPTCHA Enterprise for WAF and Google Cloud Armor integration

This document shows you how to implement a reCAPTCHA challenge page, reCAPTCHA action-tokens, and reCAPTCHA session-tokens for Google Cloud Armor.

Before you begin

Before you use a reCAPTCHA challenge page, action-tokens, or session-tokens, enable the reCAPTCHA Enterprise API.

  1. In the console, go to the reCAPTCHA Enterprise API page.

    Go to reCAPTCHA Enterprise API

  2. Verify that the name of your project appears in the project selector at the top of the page. If you don't see the name of your project, click the project selector, then select your project.

  3. Click Enable.

Implement a reCAPTCHA challenge page

When you implement a reCAPTCHA challenge page, reCAPTCHA Enterprise determines if it is 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 reCAPTCHA WAF challenge-page site key.

    Console

    1. In the 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. From the Choose platform type drop-down menu, select Website.

    6. Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge section.
    7. Turn on the Web application firewall (WAF) toggle.
    8. From the Feature drop-down menu, select Challenge page.

    9. Turn on Disable domain verification.

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

    10. Click Create key.
    11. The newly created key is listed on the reCAPTCHA keys page.

    gcloud

    To create WAF site keys, use the gcloud recaptcha keys create command:
       gcloud recaptcha keys create \
          --web \
          --display-name=DISPLAY_NAME  \
          --waf-feature=WAF_FEATURE \
          --waf-service=WAF_SERVICE \
          --integration-type=INTEGRATION_TYPE \
          --domains=DOMAIN_NAME
      

    Provide the following values:

    • DISPLAY_NAME: name for the key. Typically a site name.
    • WAF_FEATURE: name of the WAF feature. Specify challenge-page.
    • WAF_SERVICE: name of the WAF service provider. Specify CA for Google Cloud Armor.
    • INTEGRATION_TYPE: Type of integration. Specify INVISIBLE.
    • 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.

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

    REST & CMD LINE

    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:

    • PROJECT_ID: your Google Cloud project ID
    • DISPLAY_NAME: display name for the key
    • WAF_SERVICE: name of the WAF service provider. Specify CA for Google Cloud Armor.
    • WAF_FEATURE: name of the WAF feature. Specify challenge-page.
    • DOMAINS (for websites and WAF only): 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.

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

    • TYPE_OF_INTEGRATION (for websites and WAF only): Specify INVISIBLE.

    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

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

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

    PowerShell

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

    $cred = gcloud auth application-default 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": "WAF session-token test key",
      "webSettings": {
        "allowAllDomains": true,
        "allowedDomains": [
          "localhost"
        ],
    
        "integrationType": "INVISIBLE",
       
      },
      "wafSettings": {
        "wafService": "CA",
        "wafFeature": "CHALLENGE_PAGE"
        
      }
    }
    
     
    
    
    
    

  2. Configure Google Cloud Armor security policies. To learn how to use a reCAPTCHA challenge-page site key with your security policy, see Configure rules for bot management.

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 and can be valid for less time. Therefore, you must attach the action-token to a predefined request header before the token expires, so that Google Cloud Armor can evaluate the token attributes.

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

  1. Create a reCAPTCHA WAF action-token site key.

    Console

    1. In the 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. From the Choose platform type drop-down menu, select Website.

      The Domain list section appears.

    6. 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 site 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).

    7. Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge section.
    8. Turn on the Web application firewall (WAF) toggle.
    9. From the Feature drop-down menu, select Action token.

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

    11. Optional: Turn on Use checkbox challenge.

    12. Click Create key.
    13. The newly created key is listed on the reCAPTCHA keys page.

    gcloud

    To create WAF site keys, use the gcloud recaptcha keys create command:
       gcloud recaptcha keys create \
          --web \
          --display-name=DISPLAY_NAME  \
          --waf-feature=WAF_FEATURE \
          --waf-service=WAF_SERVICE \
          --integration-type=INTEGRATION_TYPE \
          --domains=DOMAIN_NAME
      

    Provide the following values:

    • DISPLAY_NAME: name for the key. Typically a site name.
    • WAF_FEATURE: name of the WAF feature. Specify action-token.
    • WAF_SERVICE: name of the WAF service provider. Specify CA for Google Cloud Armor.
    • 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.

    REST & CMD LINE

    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:

    • PROJECT_ID: your Google Cloud project ID
    • DISPLAY_NAME: display name for the key
    • WAF_SERVICE: name of the WAF service provider. Specify CA for Google Cloud Armor.
    • WAF_FEATURE: name of the WAF feature. Specify action-token.
    • DOMAINS (for websites and WAF only): 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.

    • TYPE_OF_INTEGRATION (for websites and WAF only): Specify SCORE or CHECKBOX.

    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

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

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

    PowerShell

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

    $cred = gcloud auth application-default 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": "WAF session-token test key",
      "webSettings": {
        "allowAllDomains": true,
        "allowedDomains": [
          "localhost"
        ],
    
       "integrationType": "SCORE",
    
      },
      "wafSettings": {
        "wafService": "CA",
        "wafFeature": "ACTION_TOKEN"
        
      }
    }
    
     
    
    
    
    

  2. On your web pages, install the action-token site key. For instructions, refer to the document that corresponds with the integration type of your action-token site key.

  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_SITE_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_SITE_KEY', {
            }).then(onSuccess, onError);
          };
        });
       </script>
    
     ```
    
  4. Configure Google Cloud Armor security policies. To learn how to use the reCAPTCHA action-token site key with your security policy, see Configure rules for bot management.

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 reCAPTCHA score-based site 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 the reCAPTCHA score-based site 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 user's subsequent requests and page loads on a specific domain. Session-tokens are valid for 30 minutes by default. However, if the 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 install reCAPTCHA Enterprise on every page 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 reCAPTCHA WAF session-token site key.

    Console

    1. In the 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. From the Choose platform type drop-down menu, select Website.

      The Domain list section appears.

    6. 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 site 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).

    7. Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge section.
    8. Turn on the Web application firewall (WAF) toggle.
    9. From the Feature drop-down menu, select Session token.

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

    11. Click Create key.
    12. The newly created key is listed on the reCAPTCHA keys page.

    gcloud

    To create WAF site keys, use the gcloud recaptcha keys create command:
       gcloud recaptcha keys create \
          --web \
          --display-name=DISPLAY_NAME  \
          --waf-feature=WAF_FEATURE \
          --waf-service=WAF_SERVICE \
          --integration-type=INTEGRATION_TYPE \
          --domains=DOMAIN_NAME
      

    Provide the following values:

    • DISPLAY_NAME: name for the key. Typically a site name.
    • WAF_FEATURE: name of the WAF feature. Specify session-token.
    • WAF_SERVICE: name of the WAF service provider. Specify CA for Google Cloud Armor.
    • 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.

    REST & CMD LINE

    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:

    • PROJECT_ID: your Google Cloud project ID
    • DISPLAY_NAME: display name for the key
    • WAF_SERVICE: name of the WAF service provider. Specify CA for Google Cloud Armor.
    • WAF_FEATURE: name of the WAF feature. Specify session-token.
    • DOMAINS (for websites and WAF only): 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.

    • TYPE_OF_INTEGRATION (for websites and WAF only): Specify SCORE.

    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

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

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

    PowerShell

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

    $cred = gcloud auth application-default 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": "WAF session-token test key",
      "webSettings": {
        "allowAllDomains": true,
        "allowedDomains": [
          "localhost"
        ],
    
       "integrationType": "SCORE",
    
      },
      "wafSettings": {
        "wafService": "CA",
        "wafFeature": "SESSION_TOKEN"
    
      }
    }
    
     
    
    
    
    

  2. Add the session-token site 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_SITE_KEY&waf=session" async defer></script>
      </head>
    </html>
    
  3. Configure Google Cloud Armor security policies. To learn how to use the reCAPTCHA session-token site key with your security policy, see Configure rules for bot management.

Examples of using more than one feature in a single application

You can use one or more reCAPTCHA Enterprise for WAF features in a single application.

Example 1: Using reCAPTCHA session-tokens and reCAPTCHA challenge page

You can add a reCAPTCHA session-token on pages that a user might access so that the cookie gets refreshed periodically, for example, a Login page. Configure Google Cloud Armor security policy rule to redirect the request to a reCAPTCHA challenge page when the score is low.

The following illustration shows a workflow that uses reCAPTCHA session-token and reCAPTCHA challenge page features:

Example 2: Using reCAPTCHA action-tokens and reCAPTCHA challenge page

You can add a reCAPTCHA action-token to protect a user action, such as checkout. Configure Google Cloud Armor security policy rule to redirect the request to a reCAPTCHA challenge page in any of the following conditions:

  • The score is low.
  • The action_name attribute of the action-token does not match the user action that is protected.

The following illustration shows a workflow that uses reCAPTCHA action-token and reCAPTCHA challenge page features:

The following sample script shows how to use a reCAPTCHA action-token and redirect to a reCAPTCHA challenge page with the action-token attached as header:

   <script src="https://www.google.com/recaptcha/enterprise.js?render=ACTION_TOKEN_SITE_KEY"></script>
    <script>
     function onSuccess(token) {
       const xhr = new XMLHttpRequest();
       xhr.open('GET','http://www.abc.com/checkout', false);
       xhr.setRequestHeader("X-Recaptcha-Token", token);
       xhr.onreadystatechange = function() {
         // Make sure that the request is finished and response is ready with 200
         if (this.readyState == 4 && this.status == 200) {
           // Display the response, it could be a reCAPTCHA challenge
           // page based on your Google Cloud Armor security rule settings.
            document.open();
            document.write(xhr.responseText);
            document.close();

         }
       };
       xhr.send(null);
     }

     grecaptcha.enterprise.ready(function () {
       document.getElementById("execute-button").onclick = () => {
         grecaptcha.enterprise.execute('ACTION_TOKEN_SITE_KEY', {
         }).then(onSuccess, onError);
       };
     });
    </script>

What's next