Quickstart: Setting up reCAPTCHA Enterprise on non-Google Cloud environments

This quickstart guides you how to set up reCAPTCHA Enterprise on a non-Google Cloud environment in the following scenarios:

  • You are using reCAPTCHA Enterprise in a cloud other than Google Cloud, on-premises, CRM, or SaaS environment that supports external authentication methods such as service accounts.

  • You need to use the v1 endpoint to satisfy the following requirements in your environment:

    • Your environment requires Role-Based Access Control (RBAC).

    • Your environment does not require preview and Early Access Program (EAP) features, such as Multi-factor Authentication (MFA) or Password leak detection.

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

  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

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.

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.9.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.9.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.2"

    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 tool

  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.

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.