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. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

    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. Ative a API reCAPTCHA Enterprise.

    Ative a 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 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. No Console do Google Cloud, ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  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.
  • ACCOUNT_ID: opcional. É um identificador exclusivo e persistente da conta do usuário, como um nome de conta com hash.

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",
    "user_info": {
      "account_id": "ACCOUNT_ID"
    }
  }
}

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 "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://public-preview-recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

PowerShell

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

$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,
    "user_info": {
      "account_id": "123456789"
    }
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

A seguir