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

  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.

Creating a service account for backend authentication

  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.

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

    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 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 key to use and create a 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.