Migrating from reCAPTCHA (non-Enterprise version)

This document shows you how to migrate from reCAPTCHA (non-Enterprise version) to reCAPTCHA Enterprise by using an active site key. The migration process takes approximately 5-10 minutes to complete and requires no code changes.

If you currently access the reCAPTCHA Admin console, then you are using the non-Enterprise version of reCAPTCHA, which has limited functionality and strict limits on monthly usage. For more information about the features comparison, see Comparison of features between reCAPTCHA versions.

After the migration, you become a user of reCAPTCHA Enterprise and you are charged when you exceed 1,000,000 requests per month. For more information, see reCAPTCHA Enterprise pricing.

Note: The migration process does not provide access to the additional reCAPTCHA Enterprise features such as Multi-factor authentication (MFA) or Password Leak Detection. To use these additional features, see Using reCAPTCHA Enterprise features after migration.

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.

3. Install and initialize the Cloud SDK.

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.

Migrating to reCAPTCHA Enterprise

Migrating from a non-Enterprise version of reCAPTCHA to reCAPTCHA Enterprise involves choosing an active site key from the reCAPTCHA Admin console and migrating the site key. You can migrate one or more active site keys. However, you can migrate only one site key at a time.

To execute the migration process, you must have a reCAPTCHA user account that satisfies the following requirements:

• In the reCAPTCHA Admin console, the user account is listed as an owner for the site key you want to migrate.
• The user account has the reCAPTCHA Enterprise Admin (roles/recaptchaenterprise.admin) IAM role for the Google Cloud project for which the reCAPTCHA Enterprise API is enabled. If your user account doesn't have this role, ask your administrator to grant the role, or follow the instructions on Granting, changing, and revoking access.

To migrate an active site key to reCAPTCHA Enterprise, do the following:

1. To configure authentication, run the following gcloud command:

     gcloud auth login
   

   Log in with the reCAPTCHA user account that owns the chosen site key and has the reCAPTCHA Enterprise Admin role.

2. Choose and copy an active site key that you have used to integrate reCAPTCHA with your web pages:

   1. Go to the reCAPTCHA Admin console and click .

   2. Choose a site key. The following reCAPTCHA site keys are supported for migration: reCAPTCHA v2 Checkbox, reCAPTCHA v2 Invisible, and reCAPTCHA v3.

   3. To copy the site key, click Copy site key.

3. Migrate the site key by using either the gcloud command-line tool or reCAPTCHA Enterprise API.

   gcloud

   Use the gcloud alpha recaptcha keys migrate command as shown in the following example:

    gcloud alpha recaptcha keys migrate SITE_KEY --project PROJECT-ID
   

   Provide the following values:

   • SITE_KEY: the active site key that you copied from the reCAPTCHA Admin console.
   • PROJECT-ID: the ID of the Google Cloud project for which the reCAPTCHA Enterprise API is enabled.

   REST & CMD LINE

   Before using any of the request data below, make the following replacements:

   • PROJECT_ID: the ID of the Google Cloud project for which the reCAPTCHA Enterprise API is enabled.
   • SITE_KEY: the active site key that you copied from the reCAPTCHA Admin console.

   HTTP method and URL:

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate

   To send your request, choose one of these options:

   curl

   Note: The command below assumes that you have used either gcloud init or gcloud auth login to authenticate gcloud with your user account. You can check the currently active account by executing gcloud auth list.

   Execute the following command:

   curl -X POST \
   -H "Authorization: Bearer "$(gcloud auth print-access-token) \
   -H "Content-Type: application/json; charset=utf-8" \
   -d "" \
   https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate

   PowerShell

   Note: The command below assumes that you have used either gcloud init or gcloud auth login to authenticate gcloud with your user account. You can check the currently active account by executing gcloud auth list.

   Execute the following command:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
     -Method POST `
     -Headers $headers `
     -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate" | Select-Object -Expand Content

   You should receive a JSON response similar to the following:

   {
     "name": "projects/PROJECT-ID/keys/6Ldqgs0UAAAAAIn4k7YxEB-LwEh5S9-Gv6IIWB8m",
     "displayName": "My site key",
     "webSettings": {
       "allowAllDomains": false,
       "allowedDomains": [
         recaptcha.net
       ],
       "allowAmpTraffic": false,
       "integrationType": "SCORE",
       "challengeSecurityPreference": "CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED"
     }
   }
   

4. To verify that the site key is migrated, do the following:

   gcloud

   Run the gcloud alpha recaptcha keys list command and find the migrated site key in the list of keys.

   Console

   Go to the reCAPTCHA Enterprise page and find the migrated site key in the list of keys.

   Go to reCAPTCHA Enterprise

After migrating to reCAPTCHA Enterprise, you can continue to use the siteverify method to assess a user's reCAPTCHA response token.

Note: You should not delete the site key from the reCAPTCHA Admin console or the reCAPTCHA Enterprise page of Google Cloud Console because it deletes the site key from both consoles and remove the protection that reCAPTCHA Enterprise offers.

You can revoke the reCAPTCHA Enterprise Admin (roles/recaptchaenterprise.admin) IAM role from your reCAPTCHA user account. You can either ask your administrator to revoke the access, or follow the instructions on Granting, changing, and revoking access.

What's next

• Use reCAPTCHA Enterprise features after migration.