Set up reCAPTCHA express on application servers

This document shows you how to set up reCAPTCHA express on an application server in an environment where integration of the reCAPTCHA JavaScript or mobile SDK is not feasible, for example, protection for API endpoints.

reCAPTCHA express is a feature that lets you create assessments without the client-side features. reCAPTCHA 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 Create credentials, and then select API key.

    3. Record the API key for later use.

Create a reCAPTCHA express key

To implement reCAPTCHA express, create a reCAPTCHA 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.

    Execute the gcloud recaptcha keys create command:

    Linux, macOS, or Cloud Shell

    gcloud recaptcha keys create \
--express \
--display-name=DISPLAY_NAME

    Windows (PowerShell)

    gcloud recaptcha keys create `
--express `
--display-name=DISPLAY_NAME

    Windows (cmd.exe)

    gcloud recaptcha keys create ^
--express ^
--display-name=DISPLAY_NAME

    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.

    HTTP method and URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    Request JSON body: 

    
{
  "displayName": "DISPLAY_NAME",
  "expressSettings": {}
}

    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,
"expressSettings": {
}
}

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 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. It is a string array that contains request headers in the `[key:value]` format. For example, `[key:value, key:value,...]`. We recommend that you share as many headers as possible in the required order. Ensure that the order of the headers is consistent across all requests in the same session.
  • 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://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

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://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://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"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

Interpret scores

reCAPTCHA express returns only two scores: 0.3 and 0.7. 0.3 indicates that the user interaction poses more risk and is likely fraudulent, and 0.7 indicates that the user interaction poses low risk and is likely legitimate.

If there are lack of signals, then reCAPTCHA express returns 0.7 by default.

What's next