Configurar o reCAPTCHA Express em servidores de aplicativos

Este documento mostra como configurar o reCAPTCHA Express em um servidor de aplicativos em um ambiente em que a integração do JavaScript ou do SDK para dispositivos móveis do reCAPTCHA não é viável, por exemplo, proteção para endpoints de API.

O reCAPTCHA Express é um recurso que permite criar avaliações sem os recursos do lado do cliente. O reCAPTCHA Express 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 quer atender à solicitação, redirecionar para uma página de desafio ou fazer o registro para uma 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 uso posterior.

  2. Make sure that billing is enabled for your Google Cloud project.

  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 Criar credenciais e, em seguida, selecione Chave de API.

    3. Registre a chave da API para uso posterior.

Criar uma chave reCAPTCHA Express

Para implementar o reCAPTCHA Express, crie uma chave reCAPTCHA 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 reCAPTCHA, use o comando gcloud recaptcha keys create.

    Antes de usar os dados do comando abaixo, faça estas substituições:

    • DISPLAY_NAME: o nome da chave. Geralmente, um nome de 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:

    • DISPLAY_NAME: o nome da chave. Geralmente, um nome de site.

    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

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

Grave sua chave expressa para uso posterior.

Criar uma avaliação

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

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

  • API_KEY: a chave de API que você criou para a autenticação.
  • EXPRESS_KEY: chave reCAPTCHA Express criada para seu app.
  • USER_IP_ADDRESS: o endereço IP na solicitação do dispositivo do usuário relacionado a este evento.
  • HEADER_INFO: opcional. Os cabeçalhos HTTP que o cliente enviou para o servidor do aplicativo. É uma matriz de strings que contém cabeçalhos de solicitação no formato `[key:value]`. Por exemplo, `[chave:valor, chave:valor,...]. 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. O JA3 é uma impressão digital MD5 de determinados campos do pacote de hello do cliente do TLS. 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 relacionada a este evento.
  • ACCOUNT_ID: opcional. Um identificador exclusivo e permanente da 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/",
    "firewallPolicyEvaluation": false,
    "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 expresso 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 não houver indicadores, o reCAPTCHA Express vai retornar 0.7 por padrão.

A seguir