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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    Registre o ID do projeto Google Cloud para uso posterior.

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the reCAPTCHA Enterprise API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    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 expressa 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

  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 desafio baseadas em políticas, isso define o limite de desafio universal da 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 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": {
}
}

    3. 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 do aplicativo. É 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 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 não houver sinais, o reCAPTCHA Express vai retornar 0.7 por padrão.

    A seguir