Como criar chaves reCAPTCHA

Esta página explica como criar chaves reCAPTCHA, também conhecidas como chaves de site, para verificar as interações de usuários nas páginas da Web e aplicativos para dispositivos móveis.

As chaves de site reCAPTCHA representam como o reCAPTCHA Enterprise está configurado para um site ou app. A configuração inclui opções importantes, como a exibição de testes de CAPTCHA. As chaves de site reCAPTCHA são diferentes das chaves de API.

Antes de começar

  1. Escolha o melhor método para configurar o reCAPTCHA Enterprise no ambiente e conclua a configuração.

  2. Escolha o tipo de chave adequado. Saiba mais sobre as chaves reCAPTCHA.

  3. As chaves do site reCAPTCHA para aplicativos móveis (chaves móveis) podem ser acessadas após uma análise de segurança. Entre em contato com nossa equipe de vendas para integrar seu site a esse recurso.

Como criar uma chave de site

Não há limite no número de chaves reCAPTCHA que podem ser criadas para um projeto. É melhor criar uma chave reCAPTCHA por site ou app para dispositivos móveis.

Crie chaves de site separadas para ambientes de preparação e 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 de site é usando o Console do Cloud. Como alternativa, é possível usar a API reCAPTCHA Enterprise ou a CLI do Google Cloud.

Console

  1. No console, acesse a página reCAPTCHA Enterprise.

    Acessar o reCAPTCHA Enterprise

  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. Crie uma chave de site para um site ou plataforma para dispositivos móveis. Para ver instruções, expanda a seção que corresponde à sua plataforma.
  6. Criar chaves para sites

    É possível criar chaves com base em pontuação e de caixas de seleção para sites.

    1. No menu suspenso Escolher o tipo de plataforma, selecione Site.

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

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

      Se você quiser criar uma chave de site da página de desafio, pule esta etapa.

      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 de site reCAPTCHA é exclusiva para 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).

    3. Dependendo do tipo de chave de site que você quer criar, execute as ações apropriadas:
      • Para criar uma chave de site baseada em pontuação (recomendado), faça o seguinte:
        1. Opcional: se você quiser desativar a verificação de domínio ou permitir páginas AMP, expanda a seção Firewall de aplicativo da Web (WAF), verificação de domínio, páginas AMP e desafio.
          1. Para proteger a chave de site reCAPTCHA para seu domínio e subdomínios, verifique se a opção Desativar 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. Por isso, sua chave reCAPTCHA pode ser acessada e usada por qualquer pessoa.

            Quando você desativa a verificação de domínio para as chaves do site da página de desafio, o Google Cloud Armor verifica o domínio.

          2. Para permitir que a chave de site com base em pontuação funcione com as Accelerated Mobile Pages (AMP), ative a opção Permitir que a chave funcione com páginas AMP.
        2. Clique em Criar chave.

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

      • Para criar umachave de site com caixa de seleção para mostrar um teste visível aos usuários, faça o seguinte:
        1. Expanda a seção Firewall de aplicativo da Web (WAF), verificação de domínio, páginas AMP e desafio.
        2. Para proteger a chave de site reCAPTCHA para seu domínio e subdomínios, verifique se a opção Desativar 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. Por isso, sua chave reCAPTCHA pode ser acessada e usada por qualquer pessoa.

          Quando você desativa a verificação de domínio para as chaves do site da página de desafio, o Google Cloud Armor verifica o domínio.

        3. Ative o botão Usar o 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 a dificuldade maior (mais seguro contra bots).

          Se você selecionar a dificuldade mais fácil, a probabilidade de receber o teste visual será menor.

        5. Clique em Criar chave.

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

    Criar chaves de site para o firewall de aplicativos da Web (WAF)

    Você pode criar chaves do site WAF para sites. Para criar uma chave de firewall de aplicativos da Web (WAF), faça o seguinte:

    1. No menu suspenso Escolher o tipo de plataforma, selecione Site.

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

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

      Se você quiser criar uma chave de site da página de desafio, pule esta etapa.

      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 de site reCAPTCHA é exclusiva para 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).

    3. Expanda a seção Firewall de aplicativo da Web (WAF), verificação de domínio, páginas AMP e desafio.
    4. Ative a opção Firewall do aplicativo da Web (WAF).
    5. No menu suspenso Recurso, selecione o tipo de chave WAF que você quer criar.

    6. Para as chaves do site da página de desafio, ative a opção Desativar verificação de domínio. Para chaves de site de token de ação e token de sessão, essa etapa é opcional.

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

      Quando você desativa a verificação de domínio para as chaves do site da página de desafio, o Google Cloud Armor verifica o domínio.

    7. Opcional: para chaves do site de token de ação, ative a opção Usar o desafio da caixa de seleção.

    8. Clique em Criar chave.
    9. A chave recém-criada é listada na página Chaves reCAPTCHA.

    Criar chaves de site para aplicativos de dispositivos móveis

    Em aplicativos para dispositivos móveis, só é possível criar chaves de site baseadas em pontuação.

    1. No menu suspenso Escolha o tipo de plataforma, selecione app Android ou app iOS.
    2. Dependendo da plataforma selecionada, insira os pacotes do Android ou os IDs do pacote iOS.

      Se você selecionou App Android, faça o seguinte:

      1. Na seção Lista de pacote do Android, clique em Adicionar pacote do Android.
      2. No campo pacote do Android, insira o nome do pacote do Android.

      3. (Opcional) Para incluir outro pacote, clique em Adicionar pacote do Android e digite o nome de outro pacote no campo Pacote do Android.

      Se você selecionou App iOS, faça o seguinte:

      1. Na seção Lista de ID do pacote do iOS, clique em Adicionar ID do pacote do iOS.
      2. No campo ID do pacote, insira o nome do ID do pacote do iOS.

      3. Opcional: para incluir mais um ID do pacote, clique em Adicionar ID do pacote do iOS e digite o nome dele no campo ID do pacote.

      Nos aplicativos para dispositivos móveis, a chave de site reCAPTCHA é exclusiva para os nomes de pacote especificados (por exemplo, com.google.recaptcha.test).

    3. Clique em Criar chave.

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

gcloud

Para criar chaves, use o comando gcloud recaptcha keys create:
  • Para criar chaves para sites, use o seguinte comando:

       gcloud recaptcha keys create \
          --web \
          --display-name=DISPLAY_NAME  \
          --waf-feature=WAF_FEATURE \
          --waf-service=WAF_SERVICE \
          --integration-type=INTEGRATION_TYPE \
          --domains=DOMAIN_NAME
      

    Forneça os valores a seguir:

    • DISPLAY_NAME: o nome da chave. Geralmente, um nome de site.
    • WAF_FEATURE (somente para chaves do site WAF): nome do recurso WAF. Os valores possíveis são os seguintes: challenge-page, action-token e session-token.
    • WAF_SERVICE (somente para chaves do site do WAF): nome do provedor de serviços do WAF. Especifique CA para o Google Cloud Armor.
    • INTEGRATION_TYPE: tipo de integração. Dependendo do tipo de chave, especifique os seguintes valores:
      • SCORE para chaves de sites com base em pontuação.
      • CHECKBOX para chaves de site de caixa de seleção.
      • INVISIBLE para chaves de site da página de desafio.
      • SCORE ou CHECKBOX para chaves do site de token de ação.
      • SCORE para chaves de site de token de sessão.
    • DOMAIN_NAME: domínios ou subdomínios de sites autorizados a usar a chave. Para especificar vários domínios, use um formato de lista separada por vírgulas. Opcional: para chaves de site WAF, especifique --allow-all-domains para desativar a verificação de domínio.

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

      Quando você desativa a verificação de domínio para as chaves do site da página de desafio, o Google Cloud Armor verifica o domínio.

  • Para criar chaves para apps Android, use o seguinte comando:
        gcloud recaptcha keys create \
          --android --package-names=PACKAGE_NAMES \
          --display-name=DISPLAY_NAME
        

    Forneça os valores a seguir:

    • DISPLAY_NAME: o nome da chave. Geralmente, o nome de um app.
    • PACKAGE_NAMES: nomes de pacotes do Android de apps autorizados a usar a chave. Para especificar vários nomes de pacotes, use um formato de lista separada por vírgulas.
  • Se você quiser criar uma chave para apps iOS, use o seguinte comando:
        gcloud recaptcha keys create \
          --ios --bundle-ids=BUNDLE_IDs \
          --display-name=DISPLAY_NAME
        

    Forneça os valores a seguir:

    • DISPLAY_NAME: o nome da chave. Geralmente, o nome de um app.
    • BUNDLE_IDs: os IDs do pacote de apps iOS autorizados a usar a chave. Para especificar vários IDs de pacote, use um formato de lista separada por vírgulas.
  • O exemplo a seguir mostra um exemplo de saída de criação de uma chave usando o comando gcloud recaptcha keys create.

      Created [6Ld3howaAAAAAFYDMsLz2nWFXhsnmBjdrBra5_Bq].
    

REST e linha de comando

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 qualquer um dos dados da solicitação, faça as seguintes substituições:

  • PROJECT_ID: é o ID do projeto do Google Cloud.
  • DISPLAY_NAME: nome de exibição da chave
  • WAF_SERVICE: nome do provedor de serviços WAF. Especifique CA para o Google Cloud Armor.
  • WAF_FEATURE: nome do recurso WAF.

    Dependendo do tipo de chave, especifique challenge-page, action-token ou session-token.

  • DOMAINS (somente para sites e WAF): domínios ou subdomínios de sites com permissão para usar a chave. Para especificar vários domínios, use um formato de lista separada por vírgulas. Opcional: especifique --allow-all-domains para desativar a verificação de domínio.

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

    Quando você desativa a verificação de domínio para as chaves do site da página de desafio, o Google Cloud Armor verifica o domínio.

  • TYPE_OF_INTEGRATION (somente para sites e WAF): dependendo do tipo de chave, especifique os seguintes valores:
    • SCORE para chaves de sites com base em pontuação.
    • CHECKBOX para chaves de site de caixa de seleção.
    • INVISIBLE para chaves de site da página de desafio.
    • SCORE ou CHECKBOX para chaves do site de token de ação.
    • SCORE para chaves de site de token de sessão.
  • PACKAGE_NAMES (somente para apps Android): nomes de pacotes de apps Android autorizados a usar a chave. Para especificar vários nomes de pacotes, use um formato de lista separada por vírgulas.
  • BUNDLE_IDs (somente para apps iOS): os IDs do pacote de apps iOS autorizados a usar a chave. Para especificar vários IDs de pacote, use um formato de lista separada por vírgulas.

Método HTTP e URL:

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

Corpo JSON da solicitação:


To create keys for websites:
{
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowedDomains": "DOMAINS",
    "integrationType": "TYPE_OF_INTEGRATION"
  }
}

To create keys for WAF:

{
   "displayName": "DISPLAY_NAME",
    'wafSettings': "  {
        "wafService": "WAF_SERVICE",
"wafFeature": "WAF_FEATURE"
   }
   "webSettings": {
     "allowedDomains": "DOMAINS",
     "integrationType": "TYPE_OF_INTEGRATION"
    }
}

To create keys for Android apps:
{
  "displayName": "DISPLAY_NAME",
  "androidSettings": {
  "allowedPackageNames":"PACKAGE_NAMES"
  }
}

To create keys for iOS apps:

{
  "displayName": "DISPLAY_NAME",
  "iosSettings": {
   "allowedBundleIds":"BUNDLE_IDs"

  }
}

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

curl

Salve o corpo da solicitação em um arquivo chamado request.json e execute o seguinte comando:

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

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json e execute o seguinte comando:

$cred = gcloud auth application-default 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"
  }
}

A seguir