Configurar a proteção expressa do reCAPTCHA WAF

Este documento mostra como configurar a proteção expressa do reCAPTCHA WAF (reCAPTCHA WAF expresso) em um servidor de apps sem integrar o reCAPTCHA JavaScript (Web) ou SDKs nativos para dispositivos móveis (iOS ou Android).

O reCAPTCHA WAF Express usa apenas sinais de back-end para gerar uma pontuação de risco reCAPTCHA. Use essa pontuação de risco para decidir se a solicitação precisa ser atendida, redirecionar para uma página de desafio ou registrá-la para análise posterior.

Antes de começar

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

   Registre o ID do projeto do Google Cloud para usar depois.

2. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

3. Enable the reCAPTCHA Enterprise API.

   Enable the API

4. Crie uma chave de API para autenticação:

   1. No Console do Google Cloud, acesse a página Credenciais.

      Ir para Credenciais

   2. Clique em add Criar credenciais e, em seguida, selecione Chave de API.

   3. Registre a chave de API para uso posterior.

Criar chave expressa reCAPTCHA WAF

Para implementar a proteção expressa do reCAPTCHA WAF, crie uma chave expressa do reCAPTCHA WAF.

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 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 com permissão para usar a chave. Especifique --allow-all-domains.
   • WAF_FEATURE: nome do recurso WAF. Especifique express.
   • WAF_SERVICE: nome do provedor de serviços WAF.

   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, 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 com permissão para usar a chave. Especifique --allow-all-domains.
   • WAF_FEATURE: nome do recurso WAF. Especifique express.
   • WAF_SERVICE: nome do provedor de serviços WAF.

   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": "",
     "wafFeature": "EXPRESS"
   
   }
   }
   
   

Grave sua chave expressa para uso posterior.

Criar uma avaliação

Para fazer uma solicitação do servidor de aplicativos para o reCAPTCHA Enterprise, crie uma avaliação usando o método projects.assessments.create.

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

• API_KEY: a chave de API que você criou para a autenticação.
• EXPRESS_KEY: chave expressa WAF do reCAPTCHA que você criou para o aplicativo.
• USER_IP_ADDRESS: o endereço IP na solicitação do dispositivo do usuário relacionado a esse evento.
• HEADER_INFO: opcional. Os cabeçalhos HTTP que o cliente enviou para seu servidor de aplicativos.
• JA3_FINGERPRINT: opcional. O JA3 é uma impressão digital MD5 de determinados campos do pacote "hello" do cliente TLS. Para mais informações, consulte JA3: um método para criar o perfil de clientes SSL/TLS (em inglês).
• URI_NAME: opcional. O URI que está sendo acessado pelo usuário.
• USER_AGENT: opcional. O user agent presente na solicitação do dispositivo do usuário relacionado ao evento.

Método HTTP e URL:

POST https://public-preview-recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

Corpo JSON da solicitação:

{
  "event": {
    "siteKey": "EXPRESS_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja3": "JA3_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
  }
}

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

curl -X POST \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://public-preview-recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

$headers = @{  }

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/123456789/assessments/abcdef1234000000",
  "event": {
    "token": "",
    "siteKey": "6L...",
    "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
    "userIpAddress": "1.2.3.4",
    "express": true,
    "requestedUri": "https://example.com/",
    "firewallPolicyEvaluation": false
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

A seguir

• Saiba como usar a proteção expressa do reCAPTCHA WAF com o Fastly.
• Saiba como interpretar pontuações de risco.