Criar chaves reCAPTCHA para sites

Esta página explica como criar chaves do reCAPTCHA para verificar as interações do usuário nas suas páginas da Web.

As chaves reCAPTCHA representam como o reCAPTCHA é configurado para um site. A configuração inclui opções importantes, como mostrar ou não desafios de CAPTCHA.

Antes de começar

• Prepare seu ambiente para o Google Cloud Fraud Defense.
• Verifique se você tem o papel do Identity and Access Management: administrador do reCAPTCHA Enterprise (roles/recaptchaenterprise.admin).
• Escolha o tipo de chave mais adequado ao seu caso de uso.

Criar uma chave do reCAPTCHA

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

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

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

Admin Console

1. Acesse o console do administrador do Google Cloud Fraud Defense.

   Acessar o Admin Console do Fraud Defense

2. No campo Rótulo, insira um nome que possa ser usado para identificar seu site.
3. Se quiser criar uma chave com base em pontuação, selecione Com base em pontuação (v3). Se quiser criar uma chave de caixa de seleção, selecione Desafio (v2).
4. Para adicionar um domínio, digite seu nome de domínio e clique em .

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

5. Se você não conhece o console 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 Google Cloud , um projeto Google Cloud será criado e as APIs necessárias serão ativadas para você começar. Se você já tem um projeto do Google Cloud , as APIs necessárias estão ativadas para que você possa começar.

Console do Cloud

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

   Acessar o Google Cloud Fraud Defense

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. Selecione a guia Chaves.
4. Clique em Criar chave.
5. No campo Nome de exibição, insira um nome de exibição para a chave.
6. Em Tipo de aplicativo, selecione Web.

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

7. Para proteger a chave do reCAPTCHA do seu domínio e subdomínios, verifique se a opção Desativar a verificação de domínio está desativada.

   Desativar a verificação de domínio é um risco de segurança porque não há restrições no site. Assim, qualquer pessoa pode acessar e usar sua chave do reCAPTCHA.

8. 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 do reCAPTCHA é exclusiva dos 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 será necessário especificar os subdomínios dele (por exemplo, subdomain.examplepetstore.com). As mudanças na lista de domínios podem levar até 30 minutos para entrar em vigor.

      Para usar uma chave em mais de 250 domínios, clique na chave Desativar verificação de domínio. O Google Cloud Fraud Defense vai ignorar a lista de domínios. Você precisa realizar a verificação de domínio por conta própria examinando o campo tokenProperties.hostname nas avaliações criadas.

9. Dependendo do tipo de chave do reCAPTCHA que você quer criar para seu site, faça o seguinte:

Criar chaves reCAPTCHA com base em pontuação

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

1. Se você quiser permitir que a chave baseada em pontuação funcione com Accelerated Mobile Pages (AMP) usando o componente amp-recaptcha-input, ative a opção Permitir que esta chave funcione com páginas AMP.

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

   1. Clique em Próxima etapa (opcional).
   2. Na etapa "Configurações adicionais", clique na opção Você está criando esta chave apenas para fins de teste?.
   3. Use o controle deslizante Definir pontuação para especificar uma pontuação entre 0 e 1,0.
3. Clique em Criar chave.

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

Criar chaves reCAPTCHA de caixa de seleção

Não recomendamos o uso de caixas de seleção porque elas aumentam o atrito do usuário e não melhoram significativamente a acurácia.

1. Clique em Próxima etapa (opcional).
2. Na etapa "Configurações adicionais", ative a opção Você vai usar desafios? alternar.
3. 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 quiser garantir a melhor proteção antifraude, selecione Difícil.

   Se você selecionar Fácil, os usuários terão menos chances de receber o desafio visual.

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

   1. Clique na opção Você está criando esta chave apenas para fins de teste?.
   2. Use o controle deslizante Definir pontuação para especificar uma pontuação entre 0 e 1,0.
   3. Selecione a opção Tipo de desafio adequada.
      • O Auto mostra o desafio às vezes.
      • O No CAPTCHA não mostra um desafio.
      • Desafio sem solução mostra as imagens, mas o desafio não é concluído.
   4. Clique em Criar chave.

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

Criar chaves reCAPTCHA de desafio com base em políticas

1. Clique em Próxima etapa (opcional).
2. Na etapa "Configurações adicionais", ative a opção Você vai usar desafios? alternar.
3. Selecione a opção de Teste de segurança apropriada.

   A opção de segurança de desafio define a complexidade e a frequência dos desafios de CAPTCHA mostrados ao usuário.

   Se quiser garantir a melhor proteção antifraude, selecione Forte.

   Se você selecionar Fácil, os usuários terão menos chances de receber desafios CAPTCHA menos complexos e em menor quantidade.

4. Para seu ambiente de não produção, se você quiser especificar uma pontuação para a chave ser retornada quando qualquer avaliação for criada para ela, faça o seguinte:

   1. Clique na opção Você está criando esta chave apenas para fins de teste?.
   2. Use o controle deslizante Definir pontuação para especificar uma pontuação entre 0 e 1,0.
5. Selecione o limite de pontuação para acionar testes de CAPTCHA, que é aplicável a todas as ações.
6. Clique em Criar chave.

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

gcloud

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

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

• INTEGRATION_TYPE: tipo de integração. Dependendo do tipo de chaves, especifique os seguintes valores:
  • score para chaves baseadas em pontuação.
  • checkbox para chaves de caixa de seleção.
  • policy-based-challenge para chaves de desafio com base em políticas.
  Observação:não recomendamos o uso de CHECKBOX porque ele aumenta o atrito do usuário e não melhora a precisão de forma significativa. Para mais informações, consulte as perguntas frequentes.
• DISPLAY_NAME: nome da chave. Geralmente, um nome de site.
• DOMAIN_NAME: domínios ou subdomínios de sites que podem usar 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 Google Cloud Fraud Defense vai ignorar a lista de domínios. Você precisa realizar a verificação de domínio por conta própria examinando o campo tokenProperties.hostname nas avaliações criadas.

  Desativar a verificação de domínio é um risco de segurança porque não há restrições no site. Assim, qualquer pessoa pode acessar e usar sua chave do reCAPTCHA.

  Observação:a chave do reCAPTCHA é exclusiva dos domínios e subdomínios especificados. É possível especificar mais de um domínio se você disponibilizar seu site em vários domínios. Se você especificar um domínio (por exemplo, examplepetstore.com), não será necessário especificar os subdomínios dele (por exemplo, subdomain.examplepetstore.com). As mudanças na lista de domínios podem levar até 30 minutos para entrar em vigor.
• DEFAULT_SCORE_THRESHOLD: para chaves de desafio baseadas em políticas, isso define o limite de desafio universal da chave quando um limite de pontuação personalizada não é definido.
• ACTION_SCORE_THRESHOLDS: para chaves de desafio baseadas em políticas, isso especifica a ação e a pontuação de limite correspondente entre 0,0 e 1,0. Por exemplo, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'.
  Observação:somente as pontuações finais calculadas após os desafios são retornadas nas avaliações. A pontuação inicial calculada pelo Fraud Defense é comparada ao limite.

Execute o comando gcloud recaptcha keys create:

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:

• INTEGRATION_TYPE: tipo de integração. Dependendo do tipo de chaves, especifique os seguintes valores:
  • SCORE para chaves baseadas em pontuação.
  • CHECKBOX para chaves de caixa de seleção.
  • POLICY_BASED_CHALLENGE para chaves de desafio com base em políticas.
  Observação:não recomendamos o uso de CHECKBOX porque ele aumenta o atrito do usuário e não melhora a precisão de forma significativa. Para mais informações, consulte as perguntas frequentes.
• DISPLAY_NAME: nome da chave. Geralmente, um nome de site.
• DOMAIN_NAME: domínios ou subdomínios de sites que podem usar 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 Google Cloud Fraud Defense vai ignorar a lista de domínios. Você precisa realizar a verificação de domínio por conta própria examinando o campo tokenProperties.hostname nas avaliações criadas.

  Desativar a verificação de domínio é um risco de segurança porque não há restrições no site. Assim, qualquer pessoa pode acessar e usar sua chave do reCAPTCHA.

  Observação:a chave do reCAPTCHA é exclusiva dos domínios e subdomínios especificados. É possível especificar mais de um domínio se você disponibilizar seu site em vários domínios. Se você especificar um domínio (por exemplo, examplepetstore.com), não será necessário especificar os subdomínios dele (por exemplo, subdomain.examplepetstore.com). As mudanças na lista de domínios podem levar até 30 minutos para entrar em vigor.
• DEFAULT_SCORE_THRESHOLD: para chaves de desafio baseadas em políticas, isso define o limite de desafio universal da chave quando um limite de pontuação personalizada não é definido.
• ACTION_SCORE_THRESHOLDS: para chaves de desafio baseadas em políticas, isso especifica a ação e a pontuação de limite correspondente entre 0,0 e 1,0. Por exemplo, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'.
  Observação:somente as pontuações finais calculadas após os desafios são retornadas nas avaliações. A pontuação inicial calculada pelo Fraud Defense é comparada ao limite.
• DEFAULT_SCORE_THRESHOLD: para chaves de desafio baseadas em políticas, isso define o limite de desafio universal da chave quando um limite de pontuação personalizada não é definido. Esse recurso está em pré-lançamento.
• ACTION_SCORE_THRESHOLDS: para chaves de desafio baseadas em políticas, isso especifica a ação e a pontuação de limite correspondente entre 0,0 e 1,0. Por exemplo, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'. Esse recurso está em pré-lançamento.
  Observação:somente as pontuações finais calculadas após os desafios são retornadas nas avaliações. A pontuação inicial calculada pelo reCAPTCHA é comparada ao limite.

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": "INTEGRATION_TYPE"
  }
}

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

curl

Observação: o comando a seguir pressupõe que você tenha feito login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login ou usando o Cloud Shell, que faz login automaticamente na gcloud CLI. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

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

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 gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

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

$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 do reCAPTCHA, é possível editá-las ou excluí-las. Não é possível recuperar chaves excluídas. Além disso, não é possível migrar chaves do reCAPTCHA de um projeto 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 usa a API reCAPTCHA Enterprise, precisará 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 seu aplicativo de terceiros.

Observação: aplicativos ou plug-ins de terceiros geralmente se referem a essa chave secreta legada como uma chave privada ou chave secreta.

Se você precisar da chave secreta de uma chave do reCAPTCHA Clássico, migre a chave para o reCAPTCHA em Google Cloud e encontre a chave secreta legada.

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

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

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

   Acessar o Fraud Defense

2. Selecione a guia Chaves.

3. Na seção Chaves reCAPTCHA, encontre a chave que você criou e clique nela.

   

4. Na página Detalhes principais, na guia Integração, clique em Usar chave legada. Uma caixa de diálogo vai abrir 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 chaves de caixa de seleção nas suas páginas da Web.
• Instale chaves de desafio baseadas em políticas nas suas páginas da Web.