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 JavaScript do reCAPTCHA ou o SDK para dispositivos móveis não é viável. Por exemplo, proteção para 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 registrar 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 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 Google Cloud console, 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 express do reCAPTCHA

Para implementar o reCAPTCHA Express, crie uma chave do 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 do 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.

    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: 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 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 criada para autenticação.
  • EXPRESS_KEY: chave express do reCAPTCHA criada para seu 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. É uma matriz de strings que contém cabeçalhos de solicitação no formato `[chave:valor]`. Por exemplo, `[key:value, key:value,...]`. Recomendamos que você compartilhe o máximo 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 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 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/",
    "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 vai retornar 0.7 por padrão.

A seguir