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
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Record your Google Cloud project ID for later use.Make sure that billing is enabled for your Google Cloud project. Learn how to check if billing is enabled on a project.
Enable the reCAPTCHA Enterprise API.
Create an API key for authentication:
In the Google Cloud console, go to the Credentials page.
Click
Create credentials, and then select API key.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.
In the Google Cloud console, 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.
Console
In the Google Cloud console, go to the reCAPTCHA Enterprise page.
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.
Click Create key.
- In the Display name field, enter a display name for the key.
From the Choose platform type drop-down menu, select Website.
The Domain list section appears.
-
Enter the domain name for your website:
In the Domain list section, click Add a domain.
- In the Domain field, enter the name of your domain.
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
).
- Expand the Web application firewall (WAF), Domain verification, AMP pages, and challenge
section.
- Turn on the Web application firewall (WAF) toggle.
-
- 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
. - 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
. - 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
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 ContentYou 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.