Guia de início rápido: como configurar o reCAPTCHA Enterprise em ambientes fora do Google Cloud

Neste guia de início rápido, orientamos você a configurar o reCAPTCHA Enterprise em um ambiente fora do Google Cloud nos seguintes cenários:

  • Você está usando o reCAPTCHA Enterprise em uma nuvem diferente do ambiente do Google Cloud, no local, CRM ou SaaS, compatível com métodos de autenticação externos, como contas de serviço.

  • Você precisa usar o endpoint v1 para atender aos seguintes requisitos no seu ambiente:

    • O ambiente requer o controle de acesso baseado em papéis (RBAC, na sigla em inglês).

    • O ambiente não requer recursos de visualização e do programa de acesso antecipado (EAP, na sigla em inglês), como Autenticação multifator (MFA, na sigla em inglês) ou Detecção de vazamento de senha.

Para configurar o reCAPTCHA Enterprise em um ambiente fora do Google Cloud, é necessário ativar a API reCAPTCHA Enterprise, criar uma conta de serviço e configurá-la para autenticação de back-end.

Antes de começar

  1. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  2. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

    O reCAPTCHA Enterprise exige que o faturamento seja vinculado e ativado no projeto para acessar a API. É possível ativar o faturamento usando um cartão de crédito ou um ID de projeto atual do Google Cloud. Se precisar de ajuda com o faturamento, entre em contato com o suporte do Cloud Billing.

Como ativar a API reCAPTCHA Enterprise

Console

  1. No Console do Cloud, acesse a página API reCAPTCHA Enterprise.

    Acessar a API reCAPTCHA Enterprise

  2. Verifique se o nome do projeto aparece no seletor de projetos, na parte superior da página.

    Se você não vir o nome do projeto, clique no seletor de projetos para selecioná-lo.

  3. Clique em Enable.

gcloud

  1. Para definir o projeto do Google Cloud na sessão gcloud, execute o comando gcloud config set project. Substitua PROJECT_ID pelo ID do projeto do Google Cloud.
           gcloud config set project PROJECT_ID
           
  2. Para ativar a API reCAPTCHA Enterprise, execute o comando gcloud services enable:
             gcloud services enable recaptchaenterprise.googleapis.com
           
  3. Para verificar se a API reCAPTCHA Enterprise está ativada, execute o comando gcloud services list:
             gcloud services list --enabled
           

    Verifique se a API reCAPTCHA Enterprise está listada na lista de APIs ativadas.

Como criar uma conta de serviço para autenticação de back-end

Console

  1. No Console do Cloud, acesse a página Contas de serviço.

    Acessar a página "Contas de serviço"

  2. Selecione o projeto em que você ativou a API reCAPTCHA Enterprise.
  3. Clique em Criar conta de serviço.
  4. Insira um nome de conta de serviço a ser exibido no Console do Cloud.

    O Console do Cloud gerará um ID de conta de serviço com base nesse nome. Edite o ID se for necessário. Não será possível alterar o ID depois.

  5. Opcional: digite uma descrição da conta de serviço.
  6. Clique em Criar.
  7. No menu suspenso Selecionar uma função, selecione o Agente do reCAPTCHA Enterprise.
  8. Clique em Concluído.
  9. Na lista de contas de serviço, clique no endereço de e-mail da conta de serviço que você criou.
  10. Clique em Chaves.
  11. Clique em Adicionar chave e, depois, em Criar nova chave.
  12. Na caixa de diálogo, selecione JSON e clique em Criar.

    O download de um arquivo JSON com sua chave é feito no seu computador.

  13. Clique em Fechar.

gcloud

  1. Crie a conta de serviço. Substitua NAME por um nome para a conta de serviço.

    gcloud iam service-accounts create NAME
  2. Conceda ao Agente do reCAPTCHA Enterprise (roles/recaptchaenterprise.agent) a permissão para acessar a conta de serviço. Substitua os seguintes valores:

    • PROJECT_ID pelo ID do projeto no Google Cloud.
    • NAME: o nome da conta de serviço referente à permissão.
    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/recaptchaenterprise.agent"
         
  3. Gere o arquivo de chave da conta de serviço. Substitua os seguintes valores:

    • KEY_PATH: o caminho para um novo arquivo de saída para a chave privada, por exemplo, /home/user/Downloads/service-account-file.json.
    • NAME: o nome da conta de serviço para que a chave está sendo criada.
    • PROJECT_ID pelo ID do projeto no Google Cloud.
    gcloud iam service-accounts keys create KEY_PATH --iam-account=NAME@PROJECT_ID.iam.gserviceaccount.com

Como configurar a conta de serviço para autenticação de back-end

É possível configurar a nova conta de serviço criada para autenticação de back-end usando as bibliotecas de cliente do reCAPTCHA Enterprise ou a ferramenta de linha de comando gcloud.

Bibliotecas de cliente

  1. Forneça credenciais de autenticação ao código do aplicativo definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Essa variável se aplica somente à sessão de shell atual. Se você quiser que a variável seja aplicada em sessões de shell futuras, defina a variável no arquivo de inicialização de shell, por exemplo, no arquivo ~/.bashrc ou ~/.profile.

    Linux ou macOS

    export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

    Exemplo:

    export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

    Windows

    Para PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

    Exemplo:

    $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

    Para prompt de comando:

    set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

    Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

  2. Instale a biblioteca de cliente.

    C#

    Para mais informações, consulte Como configurar um ambiente de desenvolvimento em C#.
    Install-Package Google.Cloud.RecaptchaEnterprise.V1
    

    Go

    Para mais informações, consulte Como configurar um ambiente de desenvolvimento em Go.
    go get cloud.google.com/go/recaptchaenterprise/apiv1
    

    Java

    Para mais informações, consulte Como configurar um ambiente de desenvolvimento em Java.

    Se você estiver usando o Maven, adicione o código abaixo ao arquivo pom.xml. Para mais informações sobre BOMs, consulte BOM das bibliotecas do Google Cloud Platform.

    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>com.google.cloud</groupId>
          <artifactId>libraries-bom</artifactId>
          <version>24.0.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>
    

    Se você estiver usando o Gradle, adicione isto às dependências:

    implementation platform('com.google.cloud:libraries-bom:24.0.0')
    
    implementation 'com.google.cloud:google-cloud-recaptchaenterprise'

    Se você estiver usando o sbt, adicione o seguinte às suas dependências:

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

    Se você estiver usando o Visual Studio Code, o IntelliJ ou o Eclipse, poderá adicionar bibliotecas de cliente ao projeto usando estes plug-ins de IDE:

    Os plug-ins também oferecem outras funcionalidades, como gerenciamento de chaves de contas de serviço. Consulte a documentação de cada plug-in para mais detalhes.

    Node.js

    Para mais informações, consulte Como configurar um ambiente de desenvolvimento em Node.js.
    npm install --save @google-cloud/recaptcha-enterprise
    

    PHP

    Para mais informações, consulte Como usar o PHP no Google Cloud. Adicione a biblioteca como uma dependência ao arquivo composer.json:
    composer require google/cloud-recaptcha-enterprise
    
    Se preferir, faça o download do pacote localmente.

    Python

    Para mais informações, consulte Como configurar um ambiente de desenvolvimento em Python.
    pip install --upgrade google-cloud-recaptcha-enterprise
    

    Ruby

    Para mais informações, consulte Como configurar um ambiente de desenvolvimento em Ruby.
    gem install google-cloud-recaptcha_enterprise
    

A conta de serviço que você criou está pronta para a autenticação de back-end. Ao criar uma avaliação, é possível autenticar a conta de serviço usando as bibliotecas de cliente do reCAPTCHA Enterprise.

Ferramenta gcloud

  1. Instale e inicialize o SDK do Cloud..
  2. Forneça credenciais de autenticação ao código do aplicativo definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Essa variável se aplica somente à sessão de shell atual. Se você quiser que a variável seja aplicada em sessões de shell futuras, defina a variável no arquivo de inicialização de shell, por exemplo, no arquivo ~/.bashrc ou ~/.profile.

    Linux ou macOS

    export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

    Exemplo:

    export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

    Windows

    Para PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

    Exemplo:

    $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

    Para prompt de comando:

    set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

    Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

A conta de serviço que você criou está pronta para a autenticação de back-end. Ao criar uma avaliação, é possível autenticar a conta de serviço usando a ferramenta gcloud.

A seguir

  1. Decida que tipo de chave reCAPTCHA (site) usar e crie uma chave reCAPTCHA.
  2. Instale chaves de site baseadas em pontuação ou com caixa de seleção em páginas da Web.

    OU

    Integre o reCAPTCHA Enterprise a apps Android ou apps iOS.

  3. Crie uma avaliação.

  4. Interprete uma avaliação e tome as medidas necessárias para seu site com base na pontuação.