Set up reCAPTCHA WAF express protection

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA features might have limited support, and changes to pre-GA features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

This document shows you how to set up reCAPTCHA WAF express protection (reCAPTCHA WAF express) on an application server without integrating the reCAPTCHA JavaScript (web) or native mobile (iOS or Android) SDKs.

reCAPTCHA WAF express uses only backend signals to generate a reCAPTCHA risk score (risk score). You can use this risk score to decide whether to serve the request, redirect to a challenge page, or log it for later analysis.

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. Learn how to check if billing is enabled on a 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.

Create reCAPTCHA WAF express key

To implement reCAPTCHA WAF express protection, create a reCAPTCHA WAF express site 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. 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. 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. 
   11. Click Create key.

   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 express.
     Note: You can use the express site key only for reCAPTCHA WAF express. You cannot use this key for other websites and mobile platforms.
   • WAF_SERVICE: name of the WAF service provider.
   • INTEGRATION_TYPE: Type of integration. Specify score.
   • DOMAIN_NAME: Domains or subdomains of websites allowed to use the key. Specify --allow-all-domains.

   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:

   • PROJECT_ID: your Google Cloud project ID
   • DISPLAY_NAME: display name for the key
   • WAF_SERVICE: name of the WAF service provider.
   • WAF_FEATURE: name of the WAF feature. Specify express.
     Note: You can use a reCAPTCHA WAF site key only for its corresponding feature. You cannot use this key for other websites and mobile platforms.
   • DOMAINS (for websites and WAF only): domains or subdomains of websites allowed to use the key. Specify --allow-all-domains.
   • 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

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

   $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": "WAF session-token test key",
     "webSettings": {
       "allowAllDomains": true,
       "allowedDomains": [
         "localhost"
       ],
   
      "integrationType": "SCORE",
   
     },
     "wafSettings": {
       "wafService": "CA",
       
     }
   }
   
    
   
   

Record your express site key for later use.

Create an assessment

To make a request from your application server to reCAPTCHA Enterprise, create an assessment using the projects.assessments.create method.

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

• API_KEY: The API key that you created for the authentication.
• EXPRESS_SITE_KEY: reCAPTCHA WAF express site key that you created for your application.
• USER_IP_ADDRESS: The IP address in the request from the user's device related to this event.
• HEADER_INFO: Optional. The HTTP headers that the client sent to your application server.
• JA3_FINGERPRINT: Optional. JA3 is an MD5 fingerprint of certain fields of the TLS client hello packet. For more information, see JA3 - A method for profiling SSL/TLS Clients.
• URI_NAME: Optional. The URI that is being accessed by the user.
• USER_AGENT: Optional. The user agent that is present in the request from the user's device related to this event.

HTTP method and URL:

POST https://public-preview-recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

Request JSON body:

{
  "event": {
    "siteKey": "EXPRESS_SITE_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja3": "JA3_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
  }
}

To send your request, choose one of these options:

curl

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

curl -X POST \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://public-preview-recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

PowerShell

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

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://public-preview-recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/123456789/assessments/abcdef1234000000",
  "event": {
    "token": "",
    "siteKey": "6L...",
    "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
    "userIpAddress": "1.2.3.4",
    "express": true,
    "requestedUri": "https://example.com/",
    "firewallPolicyEvaluation": false
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

What's next

• Learn about how to use reCAPTCHA WAF express protection with Fastly.
• Learn about how to interpret risk scores.