Configurar o reCAPTCHA Express em servidores de aplicativos

O reCAPTCHA express pode ser configurado em um servidor de aplicativos quando uma integração do lado do cliente com o reCAPTCHA JavaScript ou o SDK para dispositivos móveis não é viável, por exemplo, para proteção de endpoints de API.

O reCAPTCHA express é um recurso que permite criar avaliações sem uma integração ou indicadores do lado do cliente. Ele usa apenas indicadores de back-end para gerar uma pontuação de risco do reCAPTCHA. Você pode usar essa pontuação de risco para decidir se vai veicular a solicitação, redirecionar para uma página de desafio ou fazer login para análise posterior.

Antes de começar

1. No Google Cloud console do, na página do seletor de projetos, escolha ou crie um Google Cloud projeto do.

   Funções necessárias para selecionar ou criar um projeto

   • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
   • Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

   Acessar o seletor de projetos

   Registre o ID do projeto para uso posterior. Google Cloud

2. Verifique se o faturamento está ativado para o Google Cloud projeto.

3. Ative a API reCAPTCHA Enterprise.

   Funções necessárias para ativar APIs

   Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

   Ativar a API

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

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

      Ir para Credenciais

   2. Clique em Criar credenciais e selecione Chave de API.

   3. Registre a chave de API para uso posterior.

Criar uma chave reCAPTCHA express

Para implementar o reCAPTCHA express, crie uma chave reCAPTCHA express.

1. No Google Cloud console do, ative o Cloud Shell.

   Ativar o Cloud Shell

   Na parte de baixo do Google Cloud console do, uma Cloud Shell sessão é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a Google Cloud CLI 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:

   • INTEGRATION_TYPE: tipo de integração. Especifique score.
   • DISPLAY_NAME: nome da chave. Geralmente, um nome do site.

   Execute o comando gcloud recaptcha keys create:

   Linux, macOS ou Cloud Shell

   gcloud recaptcha keys create \
   --express \
   --display-name=DISPLAY_NAME

   Windows (PowerShell)

   gcloud recaptcha keys create `
   --express `
   --display-name=DISPLAY_NAME

   Windows (cmd.exe)

   gcloud recaptcha keys create ^
   --express ^
   --display-name=DISPLAY_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. Especifique score.
   • DISPLAY_NAME: nome da chave. Geralmente, um nome do site.
   • DEFAULT_SCORE_THRESHOLD: para chaves de desafio baseadas em políticas, isso define o limite de desafio universal para a chave quando um limite de pontuação personalizado não é definido. Esse recurso está na visualização.
   • 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á na visualização.
     Observação:apenas 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",
     "expressSettings": {}
   }
   
   

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

   curl

   Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

   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

   Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

   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,
   "expressSettings": {
   }
   }
   
   

Registre a chave express para uso posterior.

Criar uma avaliação

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

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

• API_KEY: a chave de API criada para a autenticação.
• EXPRESS_KEY: chave reCAPTCHA express criada 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 ao servidor de aplicativos server. É uma matriz de strings que contém cabeçalhos de solicitação no formato `[key:value]`. Por exemplo, `[key:value, key:value,...]`. Recomendamos que você compartilhe o maior número possível de cabeçalhos na ordem necessária. Verifique se a ordem dos cabeçalhos é consistente em todas as solicitações na mesma sessão.
• JA3_FINGERPRINT: opcional. JA3 é uma impressão digital MD5 de determinados campos do pacote TLS client hello. Para mais informações, consulte JA3: um método para criar perfis de clientes SSL/TLS.
• 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 a esse evento.
• ACCOUNT_ID: opcional. Um identificador exclusivo e persistente para a conta do usuário, como um nome de conta com hash.

Método HTTP e URL:

POST https://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://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://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/",
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

Interpretar pontuações

O reCAPTCHA express retorna apenas duas pontuações: 0.3 e 0.7. 0.3 indica que a interação do usuário apresenta mais risco e provavelmente é fraudulenta, e 0.7 indica que a interação do usuário apresenta baixo risco e provavelmente é legítima.

Se houver falta de indicadores, o reCAPTCHA express retornará 0.7 por padrão.

A seguir

• Saiba como interpretar pontuações de risco.
• Saiba como usar o reCAPTCHA express na camada WAF.