Configure o reCAPTCHA express em servidores de aplicações

O reCAPTCHA express pode ser configurado num servidor de aplicações 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 pontos finais da API.

O reCAPTCHA express é uma funcionalidade que lhe permite criar avaliações sem uma integração do lado do cliente nem sinais do lado do cliente. O reCAPTCHA express usa apenas sinais de back-end para gerar uma pontuação de risco do reCAPTCHA. Pode usar esta pontuação de risco para decidir se publica o pedido, se redireciona para uma página de desafio ou se o regista 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

    Registe o Google Cloud ID do projeto para utilização 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 da API para autenticação:

    1. Na Google Cloud consola, aceda à página Credenciais.

      Aceder a Credenciais

    2. Clique em Criar credenciais e, de seguida, selecione Chave da API.

    3. Registe a chave da API para utilização posterior.

Crie uma chave do reCAPTCHA express

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 qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

    • INTEGRATION_TYPE: tipo de integração. Especifique score.
    • DISPLAY_NAME: nome da chave. Normalmente, um nome do 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 ver informações de referência da API sobre tipos de chaves e tipos de integração, consulte Chave e Tipo de integração.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • INTEGRATION_TYPE: tipo de integração. Especifique score.
    • DISPLAY_NAME: nome da chave. Normalmente, um nome do site.
    • DEFAULT_SCORE_THRESHOLD: para chaves de desafio baseadas em políticas, isto define o limite de desafio universal para a chave quando não é definido um limite de pontuação personalizado. Esta funcionalidade está em pré-visualização.
    • ACTION_SCORE_THRESHOLDS: para chaves de desafio baseadas em políticas, isto 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"}'. Esta funcionalidade está em pré-visualização.

    Método HTTP e URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    Corpo JSON do pedido: 

    
{
  "displayName": "DISPLAY_NAME",
  "expressSettings": {}
}

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

    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

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

    $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

    Deve receber uma resposta JSON semelhante à seguinte:

    
{
  "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
"displayName": "DISPLAY_NAME,
"expressSettings": {
}
}

    3. Registe a sua chave expressa para utilização posterior.

    Crie uma avaliação

    Para fazer um pedido do servidor da sua aplicação ao reCAPTCHA, crie uma avaliação através do método projects.assessments.create.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • API_KEY: a chave da API que criou para a autenticação.
    • EXPRESS_KEY: chave expressa do reCAPTCHA que criou para a sua aplicação.
    • USER_IP_ADDRESS: O endereço IP no pedido do dispositivo do utilizador relacionado com este evento.
    • HEADER_INFO: opcional. Os cabeçalhos HTTP que o cliente enviou para o servidor da sua aplicação. É uma matriz de strings que contém cabeçalhos de pedidos no formato `[key:value]`. Por exemplo, `[key:value, key:value,...]`. Recomendamos que partilhe o maior número possível de cabeçalhos na ordem necessária. Certifique-se de que a ordem dos cabeçalhos é consistente em todos os pedidos na mesma sessão.
    • JA3_FINGERPRINT: opcional. O JA3 é uma impressão digital MD5 de determinados campos do pacote ClientHello do TLS. Para mais informações, consulte o artigo JA3 – Um método para criar perfis de clientes SSL/TLS.
    • URI_NAME: opcional. O URI acedido pelo utilizador.
    • USER_AGENT: opcional. O agente do utilizador presente no pedido do dispositivo do utilizador relacionado com este evento.
    • ACCOUNT_ID: opcional. Um identificador exclusivo e persistente para a conta do utilizador, 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 do pedido: 

    
{
  "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 o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

    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

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

    $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

    Deve receber uma resposta JSON semelhante à seguinte:

    {
  "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": []
  }
}

    Interprete as pontuações

    O reCAPTCHA express devolve apenas duas pontuações: 0.3 e 0.7. 0.3 indica que a interação do utilizador representa um risco maior e é provavelmente fraudulenta, e 0.7 indica que a interação do utilizador representa um risco baixo e é provavelmente legítima.

    Se não houver sinais, o reCAPTCHA express devolve 0.7 por predefinição.

    O que se segue?