Integrar o reCAPTCHA para WAF com a Cloudflare

action-token

Para gerar tokens de ação, é preciso ter o reCAPTCHA em execução nas páginas da Web. Depois que o reCAPTCHA gera um token de ação, você o anexa a um cabeçalho de solicitação predefinido sempre que precisar proteger qualquer ação do usuário, como checkout. Por padrão, os tokens de ação são válidos por 30 minutos, mas podem variar dependendo do tráfego. É necessário anexar o token de ação a um cabeçalho de solicitação predefinido antes que ele expire. Assim, o Cloudflare poderá avaliar os atributos do token.

Para implementar um token de ação reCAPTCHA, faça o seguinte:

1. Crie uma chave de token de ação para seu site.

   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:

   • DISPLAY_NAME: nome da chave. Geralmente, um nome de site.
   • INTEGRATION_TYPE: tipo de integração. Especifique score ou checkbox.
   • 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. Opcional: especifique --allow-all-domains para desativar a verificação de domínio.

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

   • WAF_FEATURE: nome do recurso do WAF. Especifique action-token.
   • WAF_SERVICE: nome do provedor de serviços de WAF. Especifique cloudflare para cloudflare.

   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 \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE

   Windows (PowerShell)

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

   Windows (cmd.exe)

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

   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. Especifique score ou checkbox.
   • 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. Opcional: especifique --allow-all-domains para desativar a verificação de domínio.

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

   • WAF_FEATURE: nome do recurso do WAF. Especifique action-token.
   • WAF_SERVICE: nome do provedor de serviços de WAF. Especifique cloudflare para cloudflare.

   Método HTTP e URL:

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

   Corpo JSON da solicitação:

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

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

   curl

   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

   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/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
    "integrationType": "SCORE",
   
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
   
     "wafFeature": "ACTION_TOKEN"
     
   
   }
   }
   
   

   Registre a chave do token de ação para uso posterior.

2. Integre o reCAPTCHA JavaScript às suas páginas da Web com a chave do token de ação que você criou. Para instruções, consulte o documento que corresponde ao tipo de integração da sua chave de token de ação.
   • Para o tipo de integração SCORE, consulte Integrar chaves baseadas em pontuação ao front-end.
   • Para o tipo de integração CHECKBOX, consulte Renderizar o widget reCAPTCHA no front-end.
3. Depois de receber o token do reCAPTCHA, anexe-o a um cabeçalho de solicitação predefinido no seguinte formato:

    X-Recaptcha-Token: value-of-your-action-token
   

   Use linguagens como XHR, Ajax ou API Fetch para anexar o token a um cabeçalho de solicitação predefinido.

   O exemplo de script a seguir mostra como proteger a ação execute e anexar o token a um cabeçalho de solicitação predefinido usando JavaScript + XHR:

     
     <script>
       src="https://www.google.com/recaptcha/enterprise.js?render=ACTION_TOKEN_KEY"></script>
   
       <script>
       function onSuccess(action_token) {
            const xhr = new XMLHttpRequest();
            xhr.open('GET','YOUR_URL', false);
            // Attach the action-token to the predefined request header
            xhr.setRequestHeader("X-Recaptcha-Token", action_token);
            xhr.send(null);
          }
          function onError(reason) {
            alert('Response promise rejected: ' + reason);
          grecaptcha.enterprise.ready(function () {
            document.getElementById("execute-button").onclick = () => {
              grecaptcha.enterprise.execute('ACTION_TOKEN_KEY', {
              }).then(onSuccess, onError);
            };
          });
         }
       </script>
     
     

session-token

O reCAPTCHA JavaScript define um token de sessão reCAPTCHA como um cookie no navegador do usuário final após a avaliação. O navegador do usuário final anexa o cookie e o atualiza enquanto o reCAPTCHA JavaScript permanece ativo.

Para fornecer um token de sessão como um cookie, instale uma chave de token de sessão em pelo menos uma das suas páginas da Web que o usuário final acessa antes da página que precisa ser protegida. Por exemplo, se você quiser proteger a página de finalização de compra, instale uma chave de token de sessão na página inicial ou na página do produto.

Você pode incluir o JavaScript do reCAPTCHA nas suas páginas da Web configurando o arquivo wrangler.toml ao instalar o pacote do reCAPTCHA para Cloudflare ou instalar a chave de sessão nas suas páginas da Web. Incluir o JavaScript do reCAPTCHA da Cloudflare integra o reCAPTCHA usando a chave de token de sessão sem a necessidade de instalação manual das chaves nas suas páginas da Web.

É possível usar esse cookie para proteger as solicitações subsequentes e carregamentos de página do usuário final em um domínio específico. Por padrão, os tokens de sessão são válidos por 30 minutos. No entanto, se o usuário final permanecer na página em que você implementou o token de sessão, o reCAPTCHA vai atualizar o token periodicamente para evitar que ele expire.

Instale tokens de sessão em todas as páginas que precisam ser protegidas pelo reCAPTCHA. Recomendamos proteger todas as páginas com o reCAPTCHA e usar as regras do Google Cloud Armor para proteger o acesso a todas elas, exceto à primeira página que os usuários finais acessarem.

   recaptcha-ca-t=value-of-your-session-token;domain=domain;expires=expiration_time

Para implementar um token de sessão reCAPTCHA, faça o seguinte:

1. Crie uma chave de token de sessão para seu site.

   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:

   • DISPLAY_NAME: nome da chave. Geralmente, um nome de site.
   • INTEGRATION_TYPE: tipo de integração. Especifique score.
   • 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. Opcional: especifique --allow-all-domains para desativar a verificação de domínio.

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

   • WAF_FEATURE: nome do recurso do WAF. Especifique session-token.
   • WAF_SERVICE: nome do provedor de serviços de WAF. Especifique cloudflare para cloudflare.

   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 \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE

   Windows (PowerShell)

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

   Windows (cmd.exe)

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

   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. Especifique score.
   • 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. Opcional: especifique --allow-all-domains para desativar a verificação de domínio.

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

   • WAF_FEATURE: nome do recurso do WAF. Especifique session-token.
   • WAF_SERVICE: nome do provedor de serviços de WAF. Especifique cloudflare para cloudflare.

   Método HTTP e URL:

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

   Corpo JSON da solicitação:

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

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

   curl

   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

   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/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
    "integrationType": "SCORE",
   
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
   
     "wafFeature": "SESSION_TOKEN"
   
   
   }
   }
   
   

   Registre a chave do token de sessão para uso posterior.

   Se você quiser injetar o JavaScript reCAPTCHA do Cloudflare, pule a próxima etapa e configure wranger.toml.

2. Adicione a chave de token de sessão e waf=session ao JavaScript do reCAPTCHA.

   O exemplo de script a seguir mostra como implementar um token de sessão em uma página da Web:

   <!DOCTYPE html>
   <html lang="en">
   <head>
    <meta charset="UTF-8">
    <title>reCAPTCHA WAF Session Token</title>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=SESSION_TOKEN_KEY&waf=session" async defer></script>
    <body></body>
   </head>
   </html>

challenge-page

Quando você implementa uma página de teste do reCAPTCHA, o reCAPTCHA redireciona para uma página intersticial em que determina se é necessário mostrar um teste de CAPTCHA para um usuário. Portanto, é possível que os testes de CAPTCHA não estejam visíveis para todos os usuários.

Para implementar uma página de teste do reCAPTCHA, faça o seguinte:

1. Crie uma chave de página de desafio para seu site.

   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:

   • DISPLAY_NAME: nome da chave. Geralmente, um nome de site.
   • INTEGRATION_TYPE: tipo de integração. Especifique invisible.
   • DOMAIN_NAME: domínios ou subdomínios de sites que podem usar a chave. Especifique --allow-all-domains.
   • WAF_FEATURE: nome do recurso do WAF. Especifique challenge-page.
   • WAF_SERVICE: nome do provedor de serviços de WAF. Especifique cloudflare para cloudflare.

   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 \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE

   Windows (PowerShell)

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

   Windows (cmd.exe)

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

   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. Especifique invisible.
   • DOMAIN_NAME: domínios ou subdomínios de sites que podem usar a chave. Especifique --allow-all-domains.
   • WAF_FEATURE: nome do recurso do WAF. Especifique challenge-page.
   • WAF_SERVICE: nome do provedor de serviços de WAF. Especifique cloudflare para cloudflare.

   Método HTTP e URL:

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

   Corpo JSON da solicitação:

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

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

   curl

   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

   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/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
     "integrationType": "INVISIBLE",
    
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
   
     "wafFeature": "CHALLENGE_PAGE"
     
   
   }
   }
   
   

   Registre a chave da página de desafio para uso posterior.

2. Para redirecionar os usuários à página de teste do reCAPTCHA e receber um token do reCAPTCHA, crie uma política de firewall com a ação redirect em páginas protegidas.

express

Para implementar o reCAPTCHA Express, crie uma chave Express.

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 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:

   • DISPLAY_NAME: nome da chave. Geralmente, um nome de site.
   • WAF_SERVICE: nome do provedor de serviços de WAF. Especifique cloudflare para cloudflare.

   Execute o comando gcloud recaptcha keys create:

   Linux, macOS ou Cloud Shell

   gcloud recaptcha keys create \
   --express \
   --display-name=DISPLAY_NAME  \
   --waf-service=WAF_SERVICE

   Windows (PowerShell)

   gcloud recaptcha keys create `
   --express `
   --display-name=DISPLAY_NAME  `
   --waf-service=WAF_SERVICE

   Windows (cmd.exe)

   gcloud recaptcha keys create ^
   --express ^
   --display-name=DISPLAY_NAME  ^
   --waf-service=WAF_SERVICE

   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.
   • WAF_SERVICE: nome do provedor de serviços de WAF. Especifique cloudflare para cloudflare.

   Método HTTP e URL:

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

   Corpo JSON da solicitação:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
     
   }
   

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

   curl

   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

   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/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
   
     
   
   }
   }
   
   

   Registre a chave expressa para uso posterior.