Configurar o Policy Engine com uma chave universal

Visualizar

Este produto ou recurso está sujeito aos Termos das Soluções 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.

Neste documento, descrevemos como configurar o Policy Engine no seu site usando uma chave universal. A chave universal é uma nova chave do Google Cloud Fraud Defense que permite a criação de regras no Policy Engine.

Com o Policy Engine, o Fraud Defense pode acionar de forma determinística testes de CAPTCHA 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, de modo que apenas uma tag script seja 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 associados (USABILITY, BALANCE, SECURITY) usando regras personalizadas baseadas em CEL.

Antes de começar

1. Prepare seu ambiente para o Google Cloud Fraud Defense.

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

   É necessário ter uma conta de faturamento vinculada e ativada para usar o Policy Engine. É possível ativar o faturamento usando um cartão de crédito ou um ID de faturamento do projeto do Google Cloud . Se precisar de ajuda com o faturamento, entre em contato com o suporte do Cloud Billing.

Criar uma chave universal

Dependendo da interface de sua preferência, escolha a opção adequada para criar uma chave universal:

Console

1. No console do Google Cloud , acesse a página Google Cloud Fraud Defense.

   Acessar o Google Cloud Fraud Defense

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 comando gcloud recaptcha keys create com a flag --universal:

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

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

API REST

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

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

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

Substitua:

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

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

Configurar domínios para o Policy Engine

Observação: para sites, a chave do reCAPTCHA é exclusiva para os domínios e subdomínios que você especificar. É possível especificar mais de um domínio se você veicular seu site em vários domínios. Se você especificar um domínio (por exemplo, examplepetstore.com), não será necessário especificar os subdomínios dele (por exemplo, subdomain.examplepetstore.com).

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

Console

1. No console do Google Cloud , acesse a página Fraud Defense.

   Acessar o Fraud Defense

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

   Se o nome do projeto não aparecer, clique no seletor de recursos e selecione o projeto.

3. Clique na guia Chaves.

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 do 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 de segurança porque não há restrições no site. Assim, sua chave do reCAPTCHA pode ser acessada e usada por qualquer pessoa.

   Insira o nome do 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 dele 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 no botã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 campo tokenProperties.hostname nas avaliações criadas.

gcloud

Para atualizar os domínios permitidos para sua chave universal usando a Google Cloud CLI, use o comando gcloud alpha recaptcha policies update 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. Todos os protected_endpoint_group ou challenge_rule_groups existentes precisam ser incluídos no arquivo POLICY.yaml para evitar que sejam excluídos.

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 chave universal.
• DOMAIN_NAME_1, DOMAIN_NAME_2: os nomes de domínio dos sites que podem usar a chave.

Observação: quando allowAllDomains é 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 campo tokenProperties.hostname nas avaliações criadas.

API REST

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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• PROJECT_ID: o ID do projeto do Google Cloud .
• KEY_ID: o ID da chave universal
• DOMAIN_NAME_1, DOMAIN_NAME_2: os nomes de domínio dos sites que podem 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 abaixo:

$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 a solicitação for bem-sucedida, ela vai retornar a configuração atualizada da política.

Observação: para usar uma política em mais de 250 domínios, defina allowAllDomains como true no corpo da solicitação. Quando allowAllDomains é 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 campo tokenProperties.hostname nas avaliações criadas.

A seguir

• Instale as chaves universais em páginas da Web.