Este documento mostra como configurar o reCAPTCHA Express em um servidor de aplicativos em um ambiente em que a integração do JavaScript do reCAPTCHA ou do 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 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
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Registre o ID do projeto do Google Cloud para uso posterior.Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
Enable the reCAPTCHA Enterprise API.
Crie uma chave de API para autenticação:
No Console do Google Cloud, acesse a página Credenciais.
Clique em
Criar credenciais e, em seguida, selecione Chave de API.Registre a chave de API para uso posterior.
Criar uma chave reCAPTCHA Express
Para implementar o reCAPTCHA Express, crie uma chave reCAPTCHA Express.
In the Google Cloud console, 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.
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: nome da chave. Geralmente, um nome de site.
Execute o gcloud recaptcha keys create (link em inglês) comando:
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 ContentVocê receberá uma resposta JSON semelhante a esta:
{ "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m", "displayName": "DISPLAY_NAME, "expressSettings": { } }
Grave sua 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 expressa que você criou para o aplicativo.
- 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 o servidor do aplicativo. É uma matriz de string 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 determinados campos do pacote de hello do cliente do TLS. 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 que está presente na solicitação do dispositivo do usuário relacionadas ao 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 apresenta baixo risco e tem probabilidade
legítimos.
Se não houver sinais, o reCAPTCHA Express retornará 0.7
por padrão.