Implementing the reCAPTCHA Enterprise for WAF and Google Cloud Armor integration features

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

Before you begin

To use reCAPTCHA action-tokens or session-tokens, enable the reCAPTCHA Enterprise API by performing the following steps:

  1. In the Cloud 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.

Implementing the reCAPTCHA challenge page

There are no implementation steps for the reCAPTCHA challenge page because reCAPTCHA Enterprise handles the implementation automatically.

As the next step, configure Google Cloud Armor security policies.

Implementing 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 new reCAPTCHA score-based or checkbox site key.
  2. To enable the action-token feature for the site key, send the site key to recaptcha-waf-eng@google.com.
  3. After the action-token feature is enabled for the site key, you receive a confirmation email.
  4. On your web pages, install the site key that is enabled. For instructions, refer to the document that corresponds with your site key:

  5. 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, and 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=SITE_KEY_ACTION_TOKEN_ENABLED"></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('SITE_KEY_ACTION_TOKEN_ENABLED', {
         }).then(onSuccess, onError);
       };
     });
    </script>

As the next step, configure Google Cloud Armor security policies.

Implementing 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 new reCAPTCHA score-based site key.
  2. To enable the session-token feature for the site key, send the site key to recaptcha-waf-eng@google.com.
  3. After the session-token feature is enabled for the site key, you receive a confirmation email.
  4. Add the site key that is enabled with the session-token feature 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=SITE_KEY_SESSION_TOKEN_ENABLED&waf=session" async defer></script>
    </head>
  </html>

As the next step, configure Google Cloud Armor security policies.

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 the 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 the 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 the reCAPTCHA challenge page with the action-token attached as header:

   <script src="https://www.google.com/recaptcha/enterprise.js?render=SITE_KEY_ACTION_TOKEN_ENABLED"></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 the 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('SITE_KEY_ACTION_TOKEN_ENABLED', {
         }).then(onSuccess, onError);
       };
     });
    </script>

What's next