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

Configura le policy relative alle verifiche

Questo documento spiega come configurare le policy di verifica con un'integrazione di Google Cloud Fraud Defense esistente.

Le policy di verifica ti consentono di attivare selettivamente le verifiche CAPTCHA in base a regole personalizzate. Queste regole decidono quando mostrare una sfida Fraud Defense in base ai punteggi di rischio, agli indirizzi IP, agli user agent, agli ASN o alle identità di bot (agente AI) verificati.

Puoi utilizzare le norme relative alle sfide con le seguenti funzionalità consigliate:

Configurazione AutoExecute: semplifica l'integrazione di JavaScript per le applicazioni client.
Sfide: attiva la verifica dell'utente quando richiesto dalle regole della sfida. Fraud Defense supporta i seguenti tipi di verifica:
- Sfide visive: chiedi agli utenti di selezionare le immagini in base a una richiesta. Per impostazione predefinita, viene selezionata una sfida visiva quando una regola viene configurata con l'opzione di sfida selezionata.
- Sfide audio: chiedi agli utenti di identificare gli indizi audio parlati come alternativa di accessibilità.
- Sfide con codice QR: chiedi agli utenti di scansionare un codice QR con il proprio dispositivo mobile per risolvere una sfida. Per utilizzare questa funzionalità, la chiave universale deve trovarsi in una lista consentita. Per aggiungere la tua chiave universale alla lista consentita, contatta il team di difesa dalle frodi all'indirizzo fraud-defense@google.com e fornisci la tua chiave universale.

Prima di iniziare

Prepara il tuo ambiente per Google Cloud Fraud Defense.
Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud . Puoi attivare la fatturazione utilizzando una carta di credito o un ID fatturazione progetto esistente. Google Cloud Se hai bisogno di assistenza per la fatturazione, contatta l'assistenza per la fatturazione Cloud.
Crea o identifica una chiave universale per il tuo progetto. Per creare una chiave, consulta la pagina Crea una chiave universale. In alternativa, puoi copiare l'ID di una chiave universale esistente completando uno dei seguenti passaggi:
- Per copiare l'ID di una chiave esistente dalla console Google Cloud :
  1. Nella console Google Cloud , vai alla pagina Google Cloud Fraud Defense.
    
    Vai a Fraud Defense
  2. Nell'elenco Chiavi reCAPTCHA, trova la chiave che vuoi copiare e fai clic su Copia negli appunti.
- Per copiare l'ID di una chiave esistente utilizzando l'API REST, chiama il metodo projects.keys.list.
- Per copiare l'ID di una chiave esistente utilizzando gcloud CLI, esegui il comando gcloud recaptcha keys list.
Pianifica l'integrazione di Fraud Defense identificando le azioni utente che vuoi proteggere (ad esempio login, signup o password_reset) e le pagine del tuo sito web che attivano queste azioni. Se utilizzi la configurazione AutoExecute, assicurati che queste azioni siano coerenti con i nomi delle azioni specificati in protected_endpoint_group.
Integra Fraud Defense nella tua pagina web. Ti consigliamo di utilizzare la configurazione di esecuzione automatica di Fraud Defense. Per istruzioni generali di configurazione, vedi Installare le chiavi universali sui siti web.

Panoramica della configurazione delle norme Fraud Defense

La configurazione dei criteri di Fraud Defense consente di personalizzare il comportamento della protezione Fraud Defense. Puoi configurare le policy di verifica utilizzando la sezione challenge_rule_groups.

Puoi visualizzare e aggiornare la configurazione delle policy utilizzando la console Google Cloud , gcloud CLI o l'API REST reCAPTCHA Enterprise.

Console

Per visualizzare o aggiornare la configurazione delle policy nella console Google Cloud , segui questi passaggi:

Nella console Google Cloud , vai alla pagina Fraud Defense.

Vai a Fraud Defense
Assicurati che il progetto sia selezionato nel selettore delle risorse.
Nella tabella Chiavi reCAPTCHA, fai clic sul nome della chiave per cui vuoi configurare i criteri di verifica.
Nella pagina Dettagli chiave, vai alla scheda Norme.
Nella sezione Gruppi di regole, puoi visualizzare, aggiungere o modificare le regole e le espressioni delle condizioni delle sfide.
Fai clic su Salva.

gcloud

Per aggiornare la configurazione delle policy per una chiave, esegui il comando gcloud alpha recaptcha policies update:

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

Per visualizzare la configurazione attuale della policy per una chiave, esegui il comando gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

API REST

Per aggiornare la configurazione della policy per una chiave, chiama il metodo 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": {}
        }
      ]
    }
  ]
}

Per visualizzare la configurazione attuale dei criteri per una chiave, chiama il metodo projects.keys.getPolicy:

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

La configurazione delle policy utilizza il formato YAML per Google Cloud CLI e il formato JSON per l'API REST. Per lo schema completo della sezione challenge_rule_groups, vedi Configurare le policy di verifica.

Per esempi di diversi casi d'uso, consulta Esempi di configurazioni di regole di verifica.

Configura le policy relative alle verifiche

Configura le policy di verifica nella sezione challenge_rule_groups della configurazione della policy di Fraud Defense. Se hai già una norma con client_settings, incluse le informazioni sui domini, puoi aggiornarla per includere le regole della norma relativa alle sfide.

La sezione challenge_rule_groups ha la seguente struttura:

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: {}

In ogni regola della sfida, il campo condition è facoltativo. Se condition non è specificato o è vuoto, la regola viene applicata senza condizioni. Inoltre, i campi challenge e no_challenge si escludono a vicenda e in ogni regola deve essere presente esattamente uno di questi campi.

Ordine di valutazione delle regole

I gruppi di regole e le relative regole interne vengono valutati in sequenza dall'alto verso il basso. Viene applicata la prima regola corrispondente. Quando nessun gruppo e nessuna regola corrisponde all'interazione, la valutazione avviene per impostazione predefinita tramite il test standard senza test mostrato, ma viene generato un punteggio di rischio per la richiesta.

Livelli di difficoltà della verifica

Puoi specificare il livello di difficoltà quando attivi una sfida. Per un elenco completo dei valori di difficoltà validi, consulta il riferimento API ChallengeSecurityPreference.

Sintassi della condizione

Il campo condition è una stringa facoltativa formattata come espressione Common Expression Language (CEL). Se condition non è specificato o è vuoto, la regola viene applicata senza condizioni. CEL fornisce operatori standard simili a C, tra cui operatori relazionali (<, <=, >, >=, ==, !=), aritmetici (+, -, /, *, %), logici (!, &&, ||) e contenitori ([], in). CEL supporta i tipi di dati primitivi comuni (bool, int, uint, double, string), i tipi di contenitori di base (lists, messages) e le costanti (come true, 1, 0.5, "hello" e [1, 2, 3]).

Durante il runtime, sono accessibili le seguenti variabili di Fraud Defense:

Variabile	Tipo	Descrizione
`score`	`double`	Il punteggio del bot Fraud Defense.
`user_ip_address`	`string`	L'indirizzo IP (IPv4 o IPv6) dell'utente che effettua la richiesta.
`user_agent`	`string`	Lo user agent dell'utente che effettua la richiesta.
`user_asn`	`int`	Il numero di sistema autonomo (ASN) dell'utente che effettua la richiesta. Ometti il prefisso `AS` (ad esempio, utilizza `12345` anziché `AS12345`).
`verified_bots`	`list(Bot)`	Un elenco di crawler o agenti automatici verificati (ad esempio indicizzatori di motori di ricerca, assistenti di ricerca AI e scraper di contenuti dei partner) che Fraud Defense ha identificato.

Sono definiti i seguenti tipi non primitivi aggiuntivi. Per l'elenco completo dei valori, vedi Bot.

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

Per ulteriori informazioni sui possibili valori di name, consulta il riferimento API Bot. Per ulteriori informazioni sui valori enum bot_type validi, consulta il riferimento API BotType.

Nelle norme relative alle sfide di Fraud Defense, puoi utilizzare una qualsiasi di queste variabili per produrre un'espressione booleana. Ad esempio, score > 0.5, user_ip_address == "192.0.2.1" e user_asn == 12345 sono espressioni di condizione valide che restituiscono un valore booleano. Tieni presente che, poiché user_asn è un tipo di numero intero, devi omettere il prefisso AS quando controlli gli ASN.

Le seguenti funzioni sono disponibili per l'utilizzo nelle condizioni delle policy di verifica di Fraud Defense:

Nome	Firma	Descrizione
`contains`	`string.contains(string) -> bool`	Controlla se l'operando stringa contiene la sottostringa.
`startsWith`	`string.startsWith(string) -> bool`	Verifica se l'operando stringa inizia con il prefisso specificato.
`endsWith`	`string.endsWith(string) -> bool`	Controlla se l'operando stringa termina con il suffisso specificato.
`size`	`size(string) -> int` `size(list) -> int` `string.size() -> int` `list.size() -> int`	Restituisce la dimensione di una stringa (numero di punti di codice) o di un elenco (numero di elementi).

Le funzioni di comprensione sono un tipo di macro integrata in CEL. Sono disponibili le seguenti comprensioni:

Nome	Firma	Descrizione	Esempio
`has`	`has(message.field) -> bool`	Controlla se un campo è disponibile.	`has(verified_bots[0].name)`
`all`	`list(A).all(A, predicate(A) -> bool) -> bool`	Controlla se tutti gli elementi `x` di un elenco `e` corrispondono al predicato `p`.	`[1, 2, 3].all(x, x > 0)`
`exists`	`list(A).exists(A, predicate(A) -> bool) -> bool`	Verifica se un elemento `x` in un elenco `e` corrisponde al predicato `p`.	`[1, 2, 3].exists(i, i % 2 != 0)`
`exists_one`	`list(A).exists_one(A, predicate(A)) -> bool`	Verifica se esattamente un elemento `x` in un elenco `e` corrisponde al predicato `p`.	`[1, 2, 2].exists_one(i, i < 2)`

Esempi di configurazioni di regole di verifica

Questa sezione contiene esempi di configurazione di regole di verifica valide.

Contesta tutte le richieste con un punteggio basso

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

Seleziona una sfida ad alto attrito per tutte le richieste con un punteggio basso

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

Contestare azioni specifiche con un punteggio basso

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

Configurare soglie delle regole diverse per azioni diverse

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

Non mostrare la verifica agli indirizzi IP nella lista consentita

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

Nota:questa regola è diversa dalla funzionalità Liste consentite di indirizzi IP per Fraud Defense.

Non mostrare la verifica a una subnet di indirizzi IP

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

Non mostrare la verifica per le richieste provenienti da ASN specifici

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: {}

Non mostrare la sfida a un agente Google

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

Mostrare la sfida in base a condizioni complesse

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

Passaggi successivi

Per valutare il token di risposta reCAPTCHA, vedi Creare valutazioni per i siti web.

Configura le policy relative alle verifiche Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Panoramica della configurazione delle norme Fraud Defense

Console

gcloud

API REST

Configura le policy relative alle verifiche

Ordine di valutazione delle regole

Livelli di difficoltà della verifica

Sintassi della condizione

Esempi di configurazioni di regole di verifica

Contesta tutte le richieste con un punteggio basso

Seleziona una sfida ad alto attrito per tutte le richieste con un punteggio basso

Contestare azioni specifiche con un punteggio basso

Configurare soglie delle regole diverse per azioni diverse

Non mostrare la verifica agli indirizzi IP nella lista consentita

Non mostrare la verifica a una subnet di indirizzi IP

Non mostrare la verifica per le richieste provenienti da ASN specifici

Non mostrare la sfida a un agente Google

Mostrare la sfida in base a condizioni complesse

Passaggi successivi

Configura le policy relative alle verifiche