Set up reCAPTCHA WAF express protection

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

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 add 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 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.
   • INTEGRATION_TYPE: Type of integration. Specify score.
   • DOMAIN_NAME: Domains or subdomains of websites allowed to use the key. Specify --allow-all-domains.
   • WAF_FEATURE: Name of the WAF feature. Specify express.
   • WAF_SERVICE: Name of the WAF service provider.

   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 --allow-all-domains.
   • WAF_FEATURE: Name of the WAF feature. Specify express.
   • WAF_SERVICE: Name of the WAF service provider.

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

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

Record your express key for later use.

Create an assessment

To make a request from your application server to reCAPTCHA, 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_KEY: reCAPTCHA WAF express 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.
• ACCOUNT_ID: Optional. A unique and persistent identifier for the user's account, such as a hashed account name.

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_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja3": "JA3_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
    "user_info": {
      "account_id": "ACCOUNT_ID"
    }
  }
}

To send your request, choose one of these options:

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"

$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,
    "user_info": {
      "account_id": "123456789"
    }
  },
  "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.