Set up reCAPTCHA Enterprise on non-Google Cloud environments

This quickstart guides you how to set up reCAPTCHA Enterprise on a cloud other than Google Cloud, on-premises, CRM, or SaaS environment that supports external authentication methods such as service accounts.

Setting up reCAPTCHA Enterprise on a non-Google Cloud environment requires enabling the reCAPTCHA Enterprise API, creating a service account, and configuring the service account for backend authentication.

Before you begin

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the reCAPTCHA Enterprise API

Console

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

gcloud

  1. To set your Google Cloud project in the gcloud session, run the gcloud config set project command. Replace PROJECT_ID with your Google Cloud project ID.
           gcloud config set project PROJECT_ID
           
  2. To enable the reCAPTCHA Enterprise API, run the gcloud services enable command:
             gcloud services enable recaptchaenterprise.googleapis.com
           
  3. To verify that the reCAPTCHA Enterprise API is enabled, run the gcloud services list command:
             gcloud services list --enabled
           

    Verify that the reCAPTCHA Enterprise API is listed in the list of enabled APIs.

Create a service account for backend authentication

Console

  1. In the Google Cloud console, go to the Service accounts page.

    Go to Service Accounts

  2. Select the project for which you enabled the reCAPTCHA Enterprise API.
  3. Click Create service account.
  4. Enter a service account name to display in the Cloud console.

    The Cloud console generates a service account ID based on this name. Edit the ID if necessary. You cannot change the ID later.

  5. Optional: Enter a description of the service account.
  6. Click Create.
  7. From the Select a role drop-down menu, select reCAPTCHA Enterprise Agent.
  8. Click Done.
  9. In the service accounts list, click the email address for the service account that you created.
  10. Click Keys.
  11. Click Add key, then select Create new key.
  12. In the dialog, select JSON and click Create.

    A JSON file that contains your key downloads to your computer.

  13. Click Close.

gcloud

  1. Create the service account. Replace NAME with a name for the service account.

    gcloud iam service-accounts create NAME
  2. Grant the reCAPTCHA Enterprise Agent (roles/recaptchaenterprise.agent) permission to the service account. Replace the following values:

    • PROJECT_ID: Your Google Cloud project ID.
    • NAME: The name of the service account to grant the permission for.
    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/recaptchaenterprise.agent"
         
  3. Generate the service account key file. Replace the following values:

    • KEY_PATH: The path to a new output file for the private key—for example, /home/user/Downloads/service-account-file.json.
    • NAME: The name of the service account to create a key for.
    • PROJECT_ID: Your Google Cloud project ID.
    gcloud iam service-accounts keys create KEY_PATH --iam-account=NAME@PROJECT_ID.iam.gserviceaccount.com

Configure the service account for backend authentication

You can configure the new service account that you created for backend authentication using either reCAPTCHA Enterprise Client Libraries or the Google Cloud CLI.

Client Libraries

  1. Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS. This variable applies only to your current shell session. If you want the variable to apply to future shell sessions, set the variable in your shell startup file, for example in the ~/.bashrc or ~/.profile file.

    Linux or macOS

    export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Replace KEY_PATH with the path of the JSON file that contains your service account key.

    For example:

    export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

    Windows

    For PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Replace KEY_PATH with the path of the JSON file that contains your service account key.

    For example:

    $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

    For command prompt:

    set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

    Replace KEY_PATH with the path of the JSON file that contains your service account key.

  2. Install the client library.

    C#

    For more information, see Setting up a C# development environment.
    Install-Package Google.Cloud.RecaptchaEnterprise.V1
    

    Go

    For more information, see Setting up a Go development environment.
    go get cloud.google.com/go/recaptchaenterprise/apiv1
    

    Java

    For more information, see Setting up a Java development environment.

    If you are using Maven, add the following to your pom.xml file. For more information about BOMs, see The Google Cloud Platform Libraries BOM.

    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>com.google.cloud</groupId>
          <artifactId>libraries-bom</artifactId>
          <version>25.4.0</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
      </dependencies>
    </dependencyManagement>
    
    <dependencies>
      <dependency>
        <groupId>com.google.cloud</groupId>
        <artifactId>google-cloud-recaptchaenterprise</artifactId>
      </dependency>
    </dependencies>
    

    If you are using Gradle, add the following to your dependencies:

    implementation platform('com.google.cloud:libraries-bom:25.4.0')
    
    implementation 'com.google.cloud:google-cloud-recaptchaenterprise'

    If you are using sbt, add the following to your dependencies:

    libraryDependencies += "com.google.cloud" % "google-cloud-recaptchaenterprise" % "2.6.1"

    If you're using Visual Studio Code, IntelliJ, or Eclipse, you can add client libraries to your project using the following IDE plugins:

    The plugins provide additional functionality, such as key management for service accounts. Refer to each plugin's documentation for details.

    Node.js

    For more information, see Setting up a Node.js development environment.
    npm install --save @google-cloud/recaptcha-enterprise
    

    PHP

    For more information, see Using PHP on Google Cloud. Add the library as a dependency to your composer.json file:
    composer require google/cloud-recaptcha-enterprise
    
    Alternatively, you can download the package locally.

    Python

    For more information, see Setting up a Python development environment.
    pip install --upgrade google-cloud-recaptcha-enterprise
    

    Ruby

    For more information, see Setting up a Ruby development environment.
    gem install google-cloud-recaptcha_enterprise
    

The service account that you created is now ready for the backend authentication. When creating an assessment, you can authenticate the service account by using the reCAPTCHA Enterprise Client Libraries.

gcloud CLI

  1. Install and initialize the Google Cloud CLI.
  2. Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS. This variable applies only to your current shell session. If you want the variable to apply to future shell sessions, set the variable in your shell startup file, for example in the ~/.bashrc or ~/.profile file.

    Linux or macOS

    export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Replace KEY_PATH with the path of the JSON file that contains your service account key.

    For example:

    export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

    Windows

    For PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Replace KEY_PATH with the path of the JSON file that contains your service account key.

    For example:

    $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

    For command prompt:

    set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

    Replace KEY_PATH with the path of the JSON file that contains your service account key.

The service account that you created is now ready for the backend authentication. When creating an assessment, you can authenticate the service account by using the gcloud CLI.

What's next

  1. Decide what type of reCAPTCHA (site) key to use and create a reCAPTCHA key.
  2. Install score-based or checkbox site keys on web pages.

    OR

    Integrate reCAPTCHA Enterprise with Android apps or iOS apps.

  3. Create an assessment.

  4. Interpret an assessment and take an appropriate action for your site based on the score.