Criar chaves reCAPTCHA para sites

Esta página explica como criar chaves reCAPTCHA (também conhecidas como chaves) para verificar as interações do usuário nas páginas da Web.

As chaves reCAPTCHA representam como o reCAPTCHA está configurado para um site. A configuração inclui opções importantes, como mostrar Desafios CAPTCHA.

Antes de começar

• Prepare seu ambiente para o reCAPTCHA.
• Verifique se você tem o seguinte papel de gerenciamento de identidade e acesso: administrador do reCAPTCHA Enterprise (roles/recaptchaenterprise.admin).
• Escolha o tipo de chave mais adequado ao seu caso de uso.

Criar uma chave reCAPTCHA

Não há limite no número de chaves reCAPTCHA que podem ser criadas para um projeto do Google Cloud. É melhor criar uma chave reCAPTCHA por site.

Recomendamos a criação de chaves reCAPTCHA separadas para preparo e ambientes de produção. Caso contrário, você corre o risco de poluir a análise de risco reCAPTCHA com dados do seu ambiente de teste.

A maneira mais simples de criar uma chave reCAPTCHA é Admin Console do reCAPTCHA. Como alternativa, use o console do Google Cloud, a API reCAPTCHA Enterprise ou a CLI do Google Cloud.

Admin Console

1. Acesse o Admin Console do reCAPTCHA.

   Acessar o Admin Console do reCAPTCHA

2. No campo Rótulo, insira um nome para identificar seu site.
3. Se você quiser criar uma chave baseada em pontuação, selecione Baseado em pontuação (v3). Se você quiser criar uma chave de caixa de seleção, selecione Desafio (v2).
4. Para adicionar um domínio, digite o nome dele e clique em .

   Para adicionar outro domínio, repita esta etapa. É possível adicionar até 250 domínios.

5. Se você não conhece o console do Google Cloud, leia os Termos de Serviço e marque a caixa de seleção.
6. Clique em Enviar.

Se você não conhece o console do Google Cloud, um projeto do Google Cloud é criado e as APIs necessárias são ativadas para você começar. Se você já tem um projeto do Google Cloud, as APIs necessárias estão ativadas para começar.

console do Cloud

1. No console do Google Cloud, acesse a página reCAPTCHA.

   Acessar o reCAPTCHA

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

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

3. Clique em Criar chave.
4. No campo Nome de exibição, insira um nome de exibição para a chave.
5. No menu Escolher o tipo de plataforma, selecione Site.

   A seção Lista de domínios é exibida.

6. Insira o nome do domínio do seu site:

   1. Na seção Lista de domínios, clique em Adicionar um domínio.
   2. No campo Domínio, digite o nome do seu domínio.

   3. Opcional: para adicionar outro domínio, clique em Adicionar um domínio e digite o nome de outro domínio no campo Domínio. É possível adicionar até 250 domínios.

      Para sites, a chave reCAPTCHA é exclusiva para os domínios e subdomínios especificados. É possível especificar mais de um domínio caso seu site seja veiculado em vários. Se você especificar um domínio (por exemplo, examplepetstore.com), não precisará especificar os subdomínios (por exemplo, subdomain.examplepetstore.com).

      Para usar uma chave em mais de 250 domínios, clique no Botão Desativar a verificação de domínio. O reCAPTCHA vai ignorar a lista de domínios. Você precisa realizar a verificação de domínio examinando o campo tokenProperties.hostname nas avaliações que criar.

7. Dependendo do tipo de chave reCAPTCHA que você quer criar para seu site, realize a ação apropriada:

Criar chaves reCAPTCHA baseadas em pontuação

Observação: criar uma chave baseada em pontuação é a opção padrão no console do Google Cloud.

1. Opcional: se você quiser desativar a verificação de domínio ou permitir páginas AMP, expandir o firewall de aplicativos da Web (WAF), verificação de domínio, páginas AMP e desafio nesta seção.
   
   1. Para proteger a chave reCAPTCHA do seu domínio e subdomínios, verifique se a opção Desativar a verificação de domínio está desativado.

      Desativar a verificação de domínio é um risco para a segurança porque não há restrições no site. Portanto, sua chave reCAPTCHA pode ser acessada e usada por qualquer pessoa.

      
   2. Se você quiser permitir que a chave baseada em pontuação funcione com Accelerated Mobile Pages (AMP), ative a opção Permitir que esta chave funcione com páginas AMP.

   3. Para seu ambiente de não produção, se quiser especificar uma pontuação, você quer que a chave retorne quando qualquer avaliação for criada para ele, faça o seguinte:

      1. Clique no botão de alternância Esta é uma chave de teste.
      2. Na caixa Pontuação, especifique uma pontuação entre 0 e 1,0.
      
   4. Clique em Criar chave.

   A chave recém-criada é listada na página Chaves reCAPTCHA.

Criar chaves reCAPTCHA da caixa de seleção

Não recomendamos o uso de chaves de caixas de seleção porque elas aumentam atrito do usuário e não melhoram a precisão de maneira significativa.

1. Expanda as opções de firewall de aplicativos da Web (WAF), verificação de domínio, páginas AMP e desafio. nesta seção.
   
2. Para proteger a chave reCAPTCHA do seu domínio e subdomínios, verifique se a opção Desativar a verificação de domínio está desativado.

   Desativar a verificação de domínio é um risco para a segurança porque não há restrições no site. Portanto, sua chave reCAPTCHA pode ser acessada e usada por qualquer pessoa.

   
3. Ative a opção Usar desafio da caixa de seleção.
   
4. Selecione a opção de Teste de segurança apropriada.

   A opção de teste de segurança controla a probabilidade de um usuário receber um teste secundário, em que os usuários precisam selecionar imagens com base em uma categoria identificada. Por exemplo, selecionar as imagens com uma motocicleta ou escadas.

   

   Se você quiser garantir a melhor proteção antifraude, selecione Dificuldade mais difícil (mais seguro) contra bots).

   Se você selecionar Dificuldade mais fácil do desafio, os usuários assistirão menos para o desafio visual.

5. Para seu ambiente de não produção, se quiser especificar uma pontuação, você quer que a chave retorne quando qualquer avaliação for criada para ele, faça o seguinte:

   1. Clique no botão de alternância Esta é uma chave de teste.
   2. Na caixa Pontuação, especifique uma pontuação entre 0 e 1,0.
   3. Selecione a opção Tipo de desafio adequada.
      • Auto mostra o desafio às vezes.
      • Sem CAPTCHA não mostra um desafio.
      • O desafio insolúvel mostra as imagens, mas o desafio não é aprovado.
      
   4. Clique em Criar chave.

   A chave recém-criada é listada na página Chaves reCAPTCHA.

gcloud

Para criar chaves reCAPTCHA, use o comando gcloud recaptcha keys create.

Antes de usar os dados do comando abaixo, faça estas substituições:

• DISPLAY_NAME: nome da chave. Geralmente, um nome de site.
• INTEGRATION_TYPE: tipo de integração. Dependendo do tipo de chave, especifique os seguintes valores:
  • score para chaves baseadas em pontuação.
  • checkbox para chaves de caixa de seleção.
  Observação: não recomendamos o uso de CHECKBOX porque isso aumenta o atrito do usuário sem melhorar significativamente a precisão. Para mais informações, consulte as Perguntas frequentes.
• DOMAIN_NAME: domínios ou subdomínios de sites que podem ser usados a chave.

  Para especificar vários domínios, use um formato de lista separada por vírgulas.

  Para usar uma chave em mais de 250 domínios, especifique --allow-all-domains para desativar a verificação de domínio. O reCAPTCHA vai ignorar a lista de domínios. Você precisa realizar a verificação de domínio examinando o campo tokenProperties.hostname nas avaliações que criar.

  Desativar a verificação de domínio é um risco à segurança porque não há restrições no site para que a chave reCAPTCHA possa ser acessada e usada por qualquer pessoa.

  Observação: A chave reCAPTCHA é exclusiva para os domínios e os subdomínios especificados por você. É possível especificar mais de um domínio exibir seu site a partir de vários domínios. Se você especificar um domínio (por exemplo, examplepetstore.com), não precisará especificar os subdomínios (por exemplo, subdomain.examplepetstore.com).

Execute o gcloud recaptcha keys create (link em inglês) comando:

Linux, macOS ou Cloud Shell

gcloud recaptcha keys create \
        --web \
        --display-name=DISPLAY_NAME  \
        --integration-type=INTEGRATION_TYPE \
        --domains=DOMAIN_NAME

Windows (PowerShell)

gcloud recaptcha keys create `
        --web `
        --display-name=DISPLAY_NAME  `
        --integration-type=INTEGRATION_TYPE `
        --domains=DOMAIN_NAME

Windows (cmd.exe)

gcloud recaptcha keys create ^
        --web ^
        --display-name=DISPLAY_NAME  ^
        --integration-type=INTEGRATION_TYPE ^
        --domains=DOMAIN_NAME

A resposta contém a chave reCAPTCHA recém-criada.

REST

Para informações de referência da API sobre tipos de integração e chave, consulte Chave e Tipo de integração.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• DISPLAY_NAME: nome da chave. Geralmente, um nome de site.
• INTEGRATION_TYPE: tipo de integração. Dependendo do tipo de chave, especifique os seguintes valores:
  • score para chaves baseadas em pontuação.
  • checkbox para chaves de caixa de seleção.
  Observação:não recomendamos o uso de CHECKBOX porque ele aumenta atrito do usuário e não melhora significativamente a precisão. Para mais informações, consulte as Perguntas frequentes.
• DOMAIN_NAME: domínios ou subdomínios de sites que podem ser usados a chave.

  Para especificar vários domínios, use um formato de lista separada por vírgulas.

  Para usar uma chave em mais de 250 domínios, especifique --allow-all-domains para desativar a verificação de domínio. O reCAPTCHA vai ignorar a lista de domínios. Você precisa realizar a verificação de domínio examinando o campo tokenProperties.hostname nas avaliações que criar.

  Desativar a verificação de domínio é um risco à segurança porque não há restrições no site para que a chave reCAPTCHA possa ser acessada e usada por qualquer pessoa.

  Observação: a chave do reCAPTCHA é exclusiva para os domínios e subdomínios que você especificar. É possível especificar mais de um domínio exibir seu site a partir de vários domínios. Se você especificar um domínio (por exemplo, examplepetstore.com), não é preciso especificar os subdomínios (por exemplo, subdomain.examplepetstore.com).

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowedDomains": "DOMAINS",
    "integrationType": "TYPE_OF_INTEGRATION"
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/project-id/keys/6Ldqgs0UAAAAAIn4k7YxEB-LwEh5S9-Gv6IIWB8m",
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowAllDomains": false,
    "allowedDomains": [
      DOMAINS
    ],
    "allowAmpTraffic": false,
    "integrationType": "SCORE",
    "challengeSecurityPreference": "CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED"
  }
}

Observação: depois de criar chaves reCAPTCHA, você pode editá-las ou excluí-las. Não é possível recuperar chaves excluídas. Além disso, não é possível migrar o reCAPTCHA chaves de um projeto do Google Cloud para outro.

(Opcional) Encontrar uma chave secreta legada do reCAPTCHA

Se você quiser fazer a integração com um aplicativo de terceiros que não use o API reCAPTCHA Enterprise, você precisa da chave secreta legada.

Para cada chave de site criada, o reCAPTCHA cria uma chave secreta legada (chave secreta legada), que pode ser usada com o aplicativo de terceiros.

Observação :não recomendamos o uso de uma chave secreta legada no front-end, porque ela ficará visível para os usuários, e invasores podem abusar do aplicativo.

Para encontrar a chave secreta legada, faça o seguinte:

1. No console do Google Cloud, acesse a página do reCAPTCHA.

   Acessar o reCAPTCHA

2. Na seção Chaves de reCAPTCHA, encontre o reCAPTCHA. que você criou e clique nela.

   

3. Na página Detalhes da chave, na guia Integração, clique em Usar chave legada. Uma caixa de diálogo é aberta com instruções sobre como usar a chave secreta legada.

   

A seguir

• Instale chaves baseadas em pontuação nas suas páginas da Web.
• Instale as chaves de caixas de seleção nas suas páginas da Web.