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, 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 registrar 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 .

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

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

    Acessar o seletor de projetos

    Anote o ID do projeto Google Cloud para usar depois.

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

  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, 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 expressa do reCAPTCHA

Para implementar o reCAPTCHA Express, crie uma chave do reCAPTCHA Express.

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

    Ativar o Cloud Shell

    Na parte de baixo do console 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 do 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 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:

    • INTEGRATION_TYPE: tipo de integração. Especifique score.
    • DISPLAY_NAME: nome da chave. Geralmente, um nome de site.
    • DEFAULT_SCORE_THRESHOLD: para chaves de teste baseadas em políticas, isso define o limite universal de teste para a chave quando um limite de pontuação personalizada não é definido. Esse recurso está em pré-lançamento.
    • 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á em pré-lançamento.

    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 abaixo: 

    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 abaixo: 

    $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 este evento.
  • HEADER_INFO: opcional. Os cabeçalhos HTTP que o cliente enviou ao servidor do aplicativo. É 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.
  • JA4_FINGERPRINT: opcional. O JA4 é uma impressão digital de determinados campos do pacote TLS Client Hello. Para mais informações, consulte Impressão digital de rede JA4+™.
  • 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"],
    "ja4": "JA4_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 não houver sinais, o reCAPTCHA Express vai retornar 0.7 por padrão.

A seguir