Guia de início rápido: como configurar o reCAPTCHA Enterprise em ambientes que não são do Google Cloud

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

  • Você está usando o reCAPTCHA Enterprise em um ambiente diferente do Google Cloud, no local, CRM ou SaaS que seja 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:

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

    • Seu ambiente não requer recursos de visualização e programa de acesso antecipado (EAP, na sigla em inglês), como a autenticação multifatorial (MFA, na sigla em inglês) ou detecção de vazamento de senha.

A configuração do reCAPTCHA Enterprise em um ambiente que não seja do Google Cloud requer a ativação da API reCAPTCHA Enterprise, a criação de uma conta de serviço e a configuração da conta de serviço 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 faturamento de um projeto do Google Cloud existente. Se você precisar de ajuda com o faturamento, entre em contato com o suporte do Cloud Billing.

Como ativar a API do reCAPTCHA Enterprise

Console

  1. No Console do Cloud, acesse a página da 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 encontrar o nome do projeto, clique no seletor e selecione seu projeto.

  3. Clique em Enable.

gcloud

  1. Para definir seu projeto do Google Cloud na sessão da 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 Select a role, selecione reCAPTCHA Enterprise Agent.
  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 selecione 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 a permissão Agente do reCAPTCHA reCAPTCHA (roles/recaptchaenterprise.agent) à 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 para conceder a 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 a qual criar uma chave.
    • 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

Configure a nova conta de serviço que você criou para autenticação de back-end usando as bibliotecas de cliente 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 só se aplica à sessão de shell atual. Assim, se você abrir uma nova sessão, precisará definir a variável novamente.

    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 -u 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>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>
    

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

    implementation platform('com.google.cloud:libraries-bom:20.6.0')
    
    compile '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" % "1.2.1"

    Caso você esteja usando o IntelliJ ou o Eclipse, poderá adicionar bibliotecas de cliente ao seu projeto usando estes plug-ins de ambiente de desenvolvimento integrado:

    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 do 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
    
    Também é possível fazer 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 agora 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 só se aplica à sessão de shell atual. Assim, se você abrir uma nova sessão, precisará definir a variável novamente.

    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 agora 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 qual tipo de chave reCAPTCHA (site) a ser usada e crie uma chave reCAPTCHA.
  2. Instale chaves de site com base em pontuação ou de caixa de seleção nas páginas da Web.

    OU

    Integre o reCAPTCHA Enterprise a apps para Android ou para iOS.

  3. Crie uma avaliação.

  4. Interpretar uma avaliação e tomar uma ação apropriada para seu site com base na pontuação.