Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Configurar políticas de desafio

Este documento explica como configurar políticas de desafio com uma integração 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 da Fraud Defense com base em pontuações de risco, endereços IP, user agents, ASNs ou identidades de bots verificados (agentes de IA).

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

Configuração AutoExecute: simplifica a integração do JavaScript para aplicativos cliente.
Desafios: aciona a verificação do usuário quando exigida pelas regras de desafio. A Defesa contra fraudes oferece suporte aos seguintes tipos de desafio:
- Desafios visuais: pedem que os usuários selecionem 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: pedem que os usuários identifiquem pistas de áudio faladas como uma alternativa de acessibilidade.
- Desafios de QR code: pedem que os usuários leiam um QR code com o dispositivo móvel para resolver um desafio. A chave universal precisa estar em uma lista de permissões para usar esse recurso. Para adicionar a chave universal à lista de permissões, entre em contato com a equipe da Defesa contra fraudes em fraud-defense@google.com e forneça a chave universal.

Antes de começar

Prepare seu ambiente para o Google Cloud Fraud Defense.
Verifique se o faturamento está ativado para o Google Cloud projeto. É possível ativar o faturamento usando um cartão de crédito ou um ID de projeto atual 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 o projeto. Para criar uma chave, consulte Criar uma chave universal. Como alternativa, é possível copiar o ID de uma chave universal atual seguindo uma destas etapas:
- Para copiar o ID de uma chave atual no Google Cloud console, faça o seguinte:
  1. No Google Cloud console, acesse a página Google Cloud Fraud Defense.
    
    Acessar o Fraud Defense
  2. Na lista Chaves reCAPTCHA, encontre a chave que você quer copiar e clique em Copiar para a área de transferência.
- Para copiar o ID de uma chave atual usando a API REST, chame o projects.keys.list método.
- Para copiar o ID de uma chave atual usando a CLI gcloud, execute o gcloud recaptcha keys list comando.
Planeje a integração do 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 em protected_endpoint_group.
Integre o Fraud Defense à sua página da Web. Recomendamos o uso da configuração AutoExecute da Defesa contra fraudes. 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 de 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 Google Cloud console, a CLI gcloud ou a API REST do reCAPTCHA Enterprise.

Console

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

No Google Cloud console, 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 para a qual você quer configurar 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 gcloud alpha recaptcha policies update comando:

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

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

gcloud alpha recaptcha policies describe --key=KEY_ID

API REST

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

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 visualizar a configuração atual da política de uma chave, chame o projects.keys.getPolicy método:

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 conferir 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

Você configura políticas de desafio na seção challenge_rule_groups da configuração da política de Fraud Defense. Se você já tiver uma política com client_settings, incluindo as informações de domínio, 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 cada regra 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 sem que nenhum desafio seja 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 ChallengeSecurityPreference referência da API.

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 semelhantes a C, incluindo relacionais (<, <=, >, >=, ==, !=), aritméticos (+, -, /, *, %), lógicos (!, &&, ||) e de contêiner ([], in). A CEL oferece suporte a 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 acessíveis:

Variável	Tipo	Descrição
`score`	`double`	A pontuação do 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 está fazendo a solicitação.
`user_asn`	`int`	O número de sistema autônomo (ASN, na sigla em inglês) do usuário que está fazendo a solicitação. Omita o prefixo `AS` (por exemplo, use `12345` em vez de `AS12345`).
`verified_bots`	`list(Bot)`	Uma lista de rastreadores ou agentes automatizados verificados (como indexadores de mecanismos de pesquisa, assistentes de pesquisa de IA e scrapers de conteúdo de parceiros) que o Fraud Defense identificou.

Os seguintes tipos não primitivos adicionais são definidos. Para conferir 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 Bot referência da API. Para mais informações sobre os valores de enum 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" e user_asn == 12345 são expressões de condição válidas que são avaliadas como booleanas. Como user_asn é um tipo 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 do 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 de string começa com o prefixo especificado.
`endsWith`	`string.endsWith(string) -> bool`	Verifica se o operando de 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 válidos de configuração de regras de desafio.

Desafiar todas as solicitações que têm 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'

Desafiar 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 diferentes

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 o 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 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 que têm uma pontuação baixa

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

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

Configurar limites de regras diferentes para ações diferentes

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 o desafio com base em condições complexas

A seguir

Configurar políticas de desafio