O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Configurar políticas de desafio

Neste documento, explicamos como configurar políticas de desafio com uma integração atual do Google Cloud Fraud Defense.

As políticas de desafio permitem acionar seletivamente testes de CAPTCHA com base em regras personalizadas. Essas regras decidem quando mostrar um desafio do Fraud Defense com base em pontuações de risco, endereços IP, user agents, ASNs, regiões geográficas ou identidades de bots verificados (agentes de IA).

É possível usar políticas de desafio com os seguintes recursos recomendados:

Configuração do AutoExecute: simplifica a integração do JavaScript para aplicativos cliente.
Desafios: aciona a verificação do usuário quando exigido pelas regras do desafio. A Fraud Defense é compatível com os seguintes tipos de desafio:
- Desafios visuais: peça aos usuários para selecionar imagens com base em um comando. Por padrão, um desafio visual é selecionado quando uma regra é configurada com a opção de desafio selecionada.
- Desafios de áudio: peça aos usuários para identificar dicas de áudio faladas como uma alternativa de acessibilidade.
- Desafios de QR code: peça aos usuários para ler um QR code com o dispositivo móvel para resolver um desafio. Sua chave universal precisa estar em uma lista de permissões para usar esse recurso. Para adicionar sua chave universal à lista de permissões, entre em contato com a equipe do Fraud Defense em fraud-defense@google.com e forneça sua chave universal.

Antes de começar

Prepare seu ambiente para o Google Cloud Fraud Defense.
Verifique se o faturamento está ativado para o projeto do Google Cloud . É 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.
Crie ou identifique uma chave universal para seu projeto. Para criar uma chave, consulte Criar uma chave universal. Se preferir, copie o ID de uma chave universal seguindo uma destas etapas:
- Para copiar o ID de uma chave do console do Google Cloud , faça o seguinte:
  1. No console do Google Cloud , acesse a página Google Cloud Fraud Defense.
    
    Acessar o Fraud Defense
  2. Na lista Chaves, encontre a chave que você quer copiar e clique em Copiar para a área de transferência.
- Para copiar o ID de uma chave usando a API REST, chame o método projects.keys.list.
- Para copiar o ID de uma chave usando a CLI gcloud, execute o comando gcloud recaptcha keys list.
Planeje sua integração com o Fraud Defense identificando as ações do usuário que você quer proteger (como login, signup ou password_reset) e quais páginas do seu site acionam essas ações. Se você usar a configuração AutoExecute, verifique se essas ações são consistentes com os nomes de ação especificados no protected_endpoint_group.
Integre a Fraud Defense à sua página da Web. Recomendamos que você use a configuração AutoExecute do Fraud Defense. Para instruções gerais de configuração, consulte Instalar chaves universais em sites.

Visão geral da configuração da política de Fraud Defense

A configuração da política do Fraud Defense permite personalizar o comportamento da proteção do Fraud Defense. É possível configurar políticas de desafio usando a seção challenge_rule_groups.

É possível visualizar e atualizar a configuração da política usando o console do Google Cloud , a CLI gcloud ou a API REST do reCAPTCHA Enterprise.

Console

Para ver ou atualizar a configuração da política no console do Google Cloud , faça o seguinte:

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

Acessar o Fraud Defense
Verifique se o projeto está selecionado no seletor de recursos.
Na tabela Chaves reCAPTCHA, clique no nome da chave em que você quer configurar as políticas de desafio.
Na página Detalhes da chave, acesse a guia Política.
Na seção Grupos de regras, é possível visualizar, adicionar ou editar as regras de desafio e as expressões de condição.
Clique em Salvar.

gcloud

Para atualizar a configuração da política de uma chave, execute o comando gcloud alpha recaptcha policies update:

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

Para conferir a configuração atual da política de uma chave, execute o comando gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

API REST

Para atualizar a configuração da política de uma chave, chame o método projects.keys.updatePolicy:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

{
  "clientSettings": {
    "allowedDomains": [
      "example.com"
    ]
  },
  "challengeRuleGroups": [
    {
      "actions": ["login"],
      "challengeRules": [
        {
          "condition": "score < 0.7",
          "challenge": {}
        }
      ]
    }
  ]
}

Para conferir a configuração atual da política de uma chave, chame o método projects.keys.getPolicy:

GET https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

A configuração da política usa o formato YAML para a Google Cloud CLI e o formato JSON para a API REST. Para ver o esquema completo da seção challenge_rule_groups, consulte Configurar políticas de desafio.

Para exemplos de diferentes casos de uso, consulte Exemplos de configurações de regras de desafio.

Configurar políticas de desafio

As políticas de desafio são configuradas na seção challenge_rule_groups da configuração da política do Fraud Defense. Se você já tiver uma política com client_settings, incluindo as informações de domínios, poderá atualizar a política para incluir as regras de política de desafio.

A seção challenge_rule_groups tem a seguinte estrutura:

challenge_rule_groups:
  - actions: [string, ...]
    challenge_rules:
      - condition: string
        challenge:
          # difficulty is optional: USABILITY | BALANCE (default) | SECURITY
          difficulty: BALANCE
        # OR no_challenge: {}
      - condition: string
        challenge:
          difficulty: BALANCE
        # OR no_challenge: {}

Em todas as regras de desafio, o campo condition é opcional. Se condition não for especificado ou estiver vazio, a regra será aplicada incondicionalmente. Além disso, os campos challenge e no_challenge são mutuamente exclusivos, e exatamente um deles precisa estar presente em cada regra.

Ordem de avaliação da regra

Os grupos de regras e as regras internas são avaliados sequencialmente de cima para baixo. A primeira regra correspondente é aplicada. Quando nenhum grupo e regra correspondem à interação, a avaliação é padronizada para o teste padrão sem nenhum desafio mostrado, mas uma pontuação de risco é gerada para a solicitação.

Níveis de dificuldade do desafio

É possível especificar o nível de dificuldade ao acionar um desafio. Para uma lista completa de valores de dificuldade válidos, consulte a referência da API ChallengeSecurityPreference.

Sintaxe da condição

O campo condition é uma string opcional formatada como uma expressão da Common Expression Language (CEL). Se condition não for especificado ou estiver vazio, a regra será aplicada incondicionalmente. A CEL fornece operadores padrão do tipo C, incluindo operadores relacionais (<, <=, >, >=, ==, !=), aritméticos (+, -, /, *, %), lógicos (!, &&, ||) e de contêiner ([], in). A CEL é compatível com tipos de dados primitivos comuns (bool, int, uint, double, string), tipos de contêiner básicos (lists, messages) e constantes (como true, 1, 0.5, "hello" e [1, 2, 3]).

No ambiente de execução, as seguintes variáveis do Fraud Defense estão disponíveis:

Variável	Tipo	Descrição
`score`	`double`	A pontuação de bot do Fraud Defense.
`user_ip_address`	`string`	O endereço IP (IPv4 ou IPv6) do usuário que está fazendo a solicitação.
`user_agent`	`string`	O user agent do usuário que faz a solicitação.
`user_asn`	`int`	O número de sistema autônomo (ASN, na sigla em inglês) do usuário que faz a solicitação. Omita o prefixo `AS` (por exemplo, use `12345` em vez de `AS12345`).
`region_code`	`string`	O código de região Unicode CLDR (com base na ISO 3166-1 alfa-2) associado ao local da solicitação (por exemplo, `"US"`, `"CA"` ou `"FR"`).
`verified_bots`	`list(Bot)`	Uma lista de rastreadores ou agentes automatizados verificados (como indexadores de mecanismos de pesquisa, assistentes de Pesquisa com IA e scrapers de conteúdo de parceiros) que o Fraud Defense identificou.

Os seguintes tipos não primitivos adicionais são definidos. Para ver a lista completa de valores, consulte Bot.

message Bot {
  name [string] - the name of the bot
  bot_type [BotType] - the type of automated agent
}

Para mais informações sobre os possíveis valores de name, consulte a referência da API Bot. Para mais informações sobre os valores de tipo enumerado bot_type válidos, consulte a referência da API BotType.

Nas políticas de desafio do Fraud Defense, é possível usar qualquer uma dessas variáveis para produzir uma expressão booleana. Por exemplo, score > 0.5, user_ip_address == "192.0.2.1", region_code == "US" e user_asn == 12345 são expressões de condição válidas que resultam em um booleano. Como user_asn é um tipo de número inteiro, é necessário omitir o prefixo AS ao verificar ASNs.

As seguintes funções estão disponíveis para uso nas condições da política de desafio da Fraud Defense:

Nome	Assinatura	Descrição
`contains`	`string.contains(string) -> bool`	Verifica se o operando de string contém a substring.
`startsWith`	`string.startsWith(string) -> bool`	Verifica se o operando da string começa com o prefixo especificado.
`endsWith`	`string.endsWith(string) -> bool`	Verifica se o operando da string termina com o sufixo especificado.
`size`	`size(string) -> int` `size(list) -> int` `string.size() -> int` `list.size() -> int`	Retorna o tamanho de uma string (número de pontos de código) ou lista (número de elementos).

As funções de compreensão são um estilo de macro integrado à CEL. As seguintes compreensões estão disponíveis:

Nome	Assinatura	Descrição	Exemplo
`has`	`has(message.field) -> bool`	Verifica se um campo está disponível.	`has(verified_bots[0].name)`
`all`	`list(A).all(A, predicate(A) -> bool) -> bool`	Verifica se todos os elementos `x` em uma lista `e` correspondem ao predicado `p`.	`[1, 2, 3].all(x, x > 0)`
`exists`	`list(A).exists(A, predicate(A) -> bool) -> bool`	Verifica se algum elemento `x` em uma lista `e` corresponde ao predicado `p`.	`[1, 2, 3].exists(i, i % 2 != 0)`
`exists_one`	`list(A).exists_one(A, predicate(A)) -> bool`	Verifica se exatamente um elemento `x` em uma lista `e` corresponde ao predicado `p`.	`[1, 2, 2].exists_one(i, i < 2)`

Exemplos de configurações de regras de desafio

Esta seção contém exemplos de configuração de regras de desafio válidas.

Desafiar todas as solicitações com uma pontuação baixa

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

Selecionar um desafio de alta fricção para todas as solicitações com uma pontuação baixa

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge:
          difficulty: 'SECURITY'

Contestar ações específicas que têm uma pontuação baixa

challenge_rule_groups:
  - actions: ['login', 'signup']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

Configurar limites de regras diferentes para ações distintas

challenge_rule_groups:
  - actions: ['login']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}
  - actions: ['signup']
    challenge_rules:
      - condition: 'score < 0.7'
        challenge: {}

Não mostrar o desafio para endereços IP na lista de permissões

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address in ["123.255.255.001", "123.255.255.002"]'
        no_challenge: {}

Observação:essa regra é diferente do recurso de listas de permissões de IP do Fraud Defense.

Não mostrar o desafio para a sub-rede de endereços IP

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address.startsWith("123.255.255")'
        no_challenge: {}

Não mostrar o desafio para solicitações de ASNs específicos

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      # Note that ASNs must be specified as integers without the AS prefix (e.g., 12345 instead of AS12345)
      - condition: 'user_asn in [12345, 67890]'
        no_challenge: {}

Não mostrar o desafio para um agente do Google

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'verified_bots.exists(e, e.name == "google-agent")'
        no_challenge: {}

Mostrar desafio com base em condições complexas

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: '(user_agent.contains("Chrome/143") && score < 0.5) || (user_agent.contains("Chrome/149") && score < 0.7)'
        challenge: {}

A seguir

Para avaliar o token de resposta do reCAPTCHA, consulte Criar avaliações para sites.

Configurar políticas de desafio Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Visão geral da configuração da política de Fraud Defense

Console

gcloud

API REST

Configurar políticas de desafio

Ordem de avaliação da regra

Níveis de dificuldade do desafio

Sintaxe da condição

Exemplos de configurações de regras de desafio

Desafiar todas as solicitações com uma pontuação baixa

Selecionar um desafio de alta fricção para todas as solicitações com uma pontuação baixa

Contestar ações específicas que têm uma pontuação baixa

Configurar limites de regras diferentes para ações distintas

Não mostrar o desafio para endereços IP na lista de permissões

Não mostrar o desafio para a sub-rede de endereços IP

Não mostrar o desafio para solicitações de ASNs específicos

Não mostrar o desafio para um agente do Google

Mostrar desafio com base em condições complexas

A seguir

Configurar políticas de desafio