Configurar o Policy Engine com uma chave universal

Visualizar

Esse produto ou recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Este documento descreve como configurar o Policy Engine no seu site usando uma chave universal. A chave universal é uma nova chave do Google Cloud Fraud Defense que oferece suporte à criação de regras no Policy Engine.

Com o Policy Engine, o Fraud Defense pode acionar desafios CAPTCHA de forma determinística com base em regras de política personalizadas que você configura. Essas regras podem decidir quando mostrar um desafio do Fraud Defense com base em pontuações de risco, endereços IP, user agents, ASNs ou identidades de bots verificados (agentes de IA).

A configuração do Policy Engine do Fraud Defense oferece dois recursos principais:

• Integração do AutoExecute (protected_endpoint_group): simplifica a integração do JavaScript de front-end inspecionando automaticamente as solicitações de rede assíncronas de saída e anexando tokens reCAPTCHA a elas. Assim, apenas uma tag de script é necessária no front-end.
• Políticas de desafio (challenge_rule_groups): determina se um desafio será mostrado em diferentes ações do usuário e configura os níveis de dificuldade de desafio associados (USABILITY, BALANCE, SECURITY) usando regras personalizadas baseadas em CEL.

Antes de começar

1. Prepare seu ambiente para o reCAPTCHA.

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

   O Fraud Defense exige que o faturamento seja vinculado e ativado no projeto para usar o Policy Engine. É possível ativar o faturamento usando um cartão de crédito ou um Google Cloud ID de projeto atual. Se você precisar de ajuda com o faturamento, entre em contato com o suporte do Cloud Billing.

Criar uma chave universal

Dependendo da interface preferida, escolha a opção adequada para criar uma chave universal:

Console

1. Noconsole, acesse a página reCAPTCHA. Google Cloud

   Acessar o reCAPTCHA

2. Verifique se o nome do projeto aparece no seletor de recursos na parte superior da página.

   Se você não vir o nome do projeto, clique no seletor de recursos, para selecioná-lo.

3. Selecione a guia Chaves.
4. Clique em Criar chave.
5. No campo Nome de exibição, insira um nome de exibição para a chave.
6. Em Tipo de aplicativo, selecione Universal.
7. Clique em Criar chave.

A chave recém-criada é listada na página Chaves reCAPTCHA.

gcloud

Para criar uma chave universal usando a Google Cloud CLI, use o gcloud recaptcha keys create comando com a --universal flag:

gcloud recaptcha keys create --universal --display-name=DISPLAY_NAME

A resposta contém a chave universal do reCAPTCHA recém-criada.

API REST

Para criar uma chave universal usando a API REST, use o projects.keys.create método e especifique universalSettings:

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

{
  "displayName": "DISPLAY_NAME",
  "universalSettings": {}
}

Substitua:

• PROJECT_ID: o ID do Google Cloud projeto
• DISPLAY_NAME: um nome de exibição para a chave, geralmente o nome do site

A resposta contém a chave universal do reCAPTCHA recém-criada.

Configurar domínios para o Policy Engine

Observação: para sites, a chave reCAPTCHA é exclusiva para os domínios e subdomínios especificados. É possível especificar mais de um domínio se o site for disponibilizado em vários domínios. Se você especificar um domínio (por exemplo, examplepetstore.com), não precisará especificar os subdomínios (por exemplo, subdomain.examplepetstore.com).

Dependendo da interface preferida, escolha a opção adequada para configurar os domínios permitidos para sua chave universal:

Console

1. Noconsole, acesse a página Fraud Defense. Google Cloud

   Acessar o Fraud Defense

2. Verifique se o nome do projeto aparece no seletor de recursos, na parte de cima da página.

   Se você não vir o nome do projeto, clique no seletor de recursos para selecioná-lo.

3. Clique na guia Chaves reCAPTCHA.

4. Identifique a chave universal que você quer configurar e clique nela.

5. Na página Detalhes da chave, clique em Editar chave.

6. Identifique a seção Configurações de uso da chave.

   Para proteger a chave reCAPTCHA para seu domínio e subdomínios, verifique se a opção Desativar verificação de domínio está desativada.

   Desativar a verificação de domínio é um risco para a segurança porque não há restrições no site, então sua chave reCAPTCHA pode ser acessada e usada por qualquer pessoa.

   Insira o nome de domínio do seu site:

   1. Na seção Lista de domínios, clique em Adicionar um domínio.
   2. No campo Domínio, digite o nome do seu domínio.
   3. Opcional: para adicionar outro domínio, clique em Adicionar um domínio e digite o nome de outro domínio no campo Domínio. É possível adicionar até 250 domínios.

7. Clique em Salvar alterações.

Observação: para usar uma política em mais de 250 domínios, clique na opção Desativar verificação de domínio. Quando a verificação de domínio está desativada, o Fraud Defense ignora a lista de domínios, e você precisa realizar a verificação de domínio por conta própria examinando o tokenProperties.hostname campo nas avaliações criadas.

gcloud

Para atualizar os domínios permitidos para sua chave universal usando a Google Cloud CLI, use o gcloud alpha recaptcha policies update comando e especifique os domínios em um arquivo de configuração de política (por exemplo, POLICY.yaml):

gcloud alpha recaptcha policies update --key=KEY_ID --policy=POLICY.yaml

Observação: O comando gcloud alpha recaptcha policies update atualiza toda a política. Qualquer protected_endpoint_group ou challenge_rule_groups precisa ser incluído no arquivo POLICY.yaml para evitar a exclusão.

O arquivo POLICY.yaml precisa especificar os domínios permitidos em clientSettings:

clientSettings:
  allowedDomains:
    - DOMAIN_NAME_1
    - DOMAIN_NAME_2

Como alternativa, para permitir todos os domínios e desativar a verificação de domínio, defina allowAllDomains como true no arquivo POLICY.yaml:

clientSettings:
  allowAllDomains: true

Substitua:

• KEY_ID: o ID ou o nome completo do recurso da sua chave universal
• DOMAIN_NAME_1, DOMAIN_NAME_2: os nomes de domínio de sites permitidos para usar a chave

Observação: quando allowAllDomains está definido como true, o Fraud Defense ignora a lista de domínios, e você precisa realizar a verificação de domínio por conta própria examinando o tokenProperties.hostname campo nas avaliações criadas.

API REST

Para atualizar os domínios permitidos para sua chave universal usando a API REST, use o projects.keys.updatePolicy método.

Antes de usar qualquer um dos dados da solicitação, faça as seguintes substituições:

• PROJECT_ID: o ID do seu Google Cloud projeto
• KEY_ID: o ID da sua chave universal
• DOMAIN_NAME_1, DOMAIN_NAME_2: os nomes de domínio de sites permitidos para usar a chave

Método HTTP e URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains

Corpo JSON da solicitação:

{
"clientSettings": {
  "allowedDomains": [
    "DOMAIN_NAME_1",
    "DOMAIN_NAME_2"
  ],
  "allowAllDomains": false
}
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X PATCH \
     -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/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains" | Select-Object -Expand Content

Se for bem-sucedida, a solicitação vai retornar a configuração de política atualizada.

Observação: para usar uma política em mais de 250 domínios, defina allowAllDomains como true no corpo da solicitação. Quando allowAllDomains está definido como true, o Fraud Defense ignora a lista de domínios, e você precisa realizar a verificação de domínio por conta própria examinando o tokenProperties.hostname campo nas avaliações criadas.

A seguir

• Instale chaves universais em páginas da Web.