Quickstart: Setting up reCAPTCHA Enterprise on Google Cloud

This quickstart guides you how to set up reCAPTCHA Enterprise on Google Cloud. Setting up reCAPTCHA Enterprise on Google Cloud requires enabling the reCAPTCHA Enterprise API, creating a service account, and configuring the service account for backend authentication. This document is applicable to both PaaS options such as App Engine and IaaS options such as virtual machines in Compute Engine.

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

  2. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

    reCAPTCHA Enterprise requires billing to be linked and enabled on the project to access the API. You can enable billing by using either a credit card or an existing Google Cloud project billing ID. If you require assistance with billing, contact the Cloud Billing Support.

Enabling the reCAPTCHA Enterprise API

Console

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

Creating a service account for backend authentication

Console

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

Configuring the service account for backend authentication

The way you configure your service account for backend authentication in Google Cloud environment depends on the products you use, such as App Engine, Compute Engine, and Google Kubernetes Engine (GKE).

App Engine

For App Engine, you can authenticate the service account by using the reCAPTCHA Enterprise Client Libraries.

  1. Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS. This variable only applies to your current shell session, so if you open a new session, set the variable again.

    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 -u 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>20.6.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:20.6.0')
    
    compile 'com.google.cloud:google-cloud-recaptchaenterprise'

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

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

    If you're using 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.

Compute Engine

You can configure the new service account that you created for backend authentication using either reCAPTCHA Enterprise Client Libraries or the gcloud command-line tool.

reCAPTCHA Enterprise Client Libraries

  1. Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS. This variable only applies to your current shell session, so if you open a new session, set the variable again.

    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 -u 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>20.6.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:20.6.0')
    
    compile 'com.google.cloud:google-cloud-recaptchaenterprise'

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

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

    If you're using 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 command-line

  1. Install and initialize the Cloud SDK.
  2. Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS. This variable only applies to your current shell session, so if you open a new session, set the variable again.

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

GKE

  1. Use Workload Identity with a service account to access Google Cloud services from applications running within GKE.

    For more information about creating service accounts, see create service accounts for backend authentication.

  2. Authenticate to Google Cloud using Workload Identity.

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.