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 reCAPTCHA Não é possível usar JavaScript ou SDK para dispositivos móveis. 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. 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 veicular a 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. 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 Criar credenciais e, em seguida, 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. 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": {
}
}

Registre a chave expressa para uso posterior.

Criar uma avaliação

Para fazer uma solicitação do servidor de aplicativos ao reCAPTCHA, crie uma avaliação usando o 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 à este evento.
  • HEADER_INFO: opcional. Os cabeçalhos HTTP que o cliente enviou para seu aplicativo servidor. É 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. A ordem dos cabeçalhos precisa ser consistente em todas as solicitações na mesma sessão.
  • JA3_FINGERPRINT: opcional. O JA3 é uma impressão digital MD5 de certos campos da camada TLS do pacote "client hello". Para mais informações, consulte JA3: um método para criar o perfil 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 Express retorna apenas duas pontuações: 0.3 e 0.7. 0.3: indica que a interação do usuário representa mais risco e é provavelmente fraudulenta. e 0.7 indica que a interação do usuário representa baixo risco e é provável legítimos.

Se não houver sinais, o reCAPTCHA Express retornará 0.7 por padrão.

A seguir