Set up reCAPTCHA Enterprise on non-Google Cloud environments

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.

Note:

• If you are deploying the backend of reCAPTCHA Enterprise in Google Cloud, see Quickstart: Setting up reCAPTCHA Enterprise on Google Cloud.
• If you want to use API Keys for backend authentication, see Quickstart: Setting up reCAPTCHA Enterprise on non-Google Cloud environments using API Keys.

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

Note: To enable and get started with reCAPTCHA Enterprise on Google Cloud, you do not need to enable billing for your Google Cloud project. However, we recommend enabling billing to ensure that your site remains protected after you exceed the free monthly usage limit of reCAPTCHA Enterprise. For more information, see Billing information.

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.

Note: You must have specific permissions to create service accounts and service account keys. For more information, see the Cloud IAM documentation.

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>26.16.0</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
     </dependencies>
   </dependencyManagement>
   
   <dependencies>
     <dependency>
       <groupId>com.google.cloud</groupId>
       <artifactId>google-cloud-recaptchaenterprise</artifactId>
     </dependency>

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

   implementation 'com.google.cloud:google-cloud-recaptchaenterprise:3.16.0'

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

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

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

   • Cloud Code for VS Code
   • Cloud Code for IntelliJ
   • Cloud Tools for Eclipse

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

   Note: Cloud Java client libraries do not currently support Android.

   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 the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

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.