Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Configura le policy relative alle verifiche

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

Le policy di verifica ti consentono di attivare in modo selettivo le verifiche CAPTCHA in base a regole personalizzate. Queste regole decidono quando mostrare una verifica di Fraud Defense in base a scoring del rischio, indirizzi IP, user agent, ASN, regioni geografiche o identità di bot (agenti AI) verificati.

Puoi utilizzare le policy di verifica con le seguenti funzionalità consigliate:

Configurazione di AutoExecute: semplifica l'integrazione di JavaScript per le applicazioni client.
Verifiche: attiva la verifica dell'utente quando richiesto dalle regole di verifica. Fraud Defense supporta i seguenti tipi di verifica:
- Sfide visive: chiedi agli utenti di selezionare le immagini in base a un prompt. Per impostazione predefinita, viene selezionata una verifica visiva quando viene configurata una regola con l'opzione di verifica selezionata.
- Sfide audio: chiedi agli utenti di identificare segnali audio parlati come alternativa di accessibilità.
- Sfide con codici QR: chiedi agli utenti di scansionare un codice QR con il proprio dispositivo mobile per risolvere una sfida. La tua chiave universale deve essere inclusa in una lista consentita per utilizzare questa funzionalità. Per aggiungere la chiave universale alla lista consentita, contatta il team di Fraud Defense 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 del progetto Google Cloud esistente. 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 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 , segui questi passaggi:
  1. Nella console Google Cloud , vai alla pagina Google Cloud Fraud Defense.
    
    Vai a Fraud Defense
  2. Nell'elenco Chiavi, 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 AutoExecute di Fraud Defense. Per istruzioni generali sulla configurazione, consulta Installa le chiavi universali sui siti web.

Panoramica della configurazione delle policy di Fraud Defense

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

Puoi visualizzare e aggiornare la configurazione della policy utilizzando la console Google Cloud , gcloud CLI o l'API REST di 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 le policy di verifica.
Nella pagina Dettagli chiave, vai alla scheda Policy.
Nella sezione Gruppi di regole, puoi visualizzare, aggiungere o modificare le regole di verifica e le espressioni di condizione.
Fai clic su Salva.

gcloud

Per aggiornare la configurazione della 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 della policy attuale 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 della policy corrente per una chiave, chiama il metodo projects.keys.getPolicy:

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

La configurazione della 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, consulta Configura le policy di verifica.

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

Configura le policy di verifica

Puoi configurare le policy di verifica nella sezione challenge_rule_groups della configurazione della policy di Fraud Defense. Se hai già una policy con client_settings, incluse le informazioni sui domini, puoi aggiornarla in modo da includere le regole della policy di verifica.

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 di verifica, il campo condition è facoltativo. Se condition non è specificato o è vuoto, la regola viene applicata in modo incondizionato. Inoltre, i campi challenge e no_challenge si escludono a vicenda ed esattamente uno di questi deve essere presente in ogni regola.

Ordine di valutazione delle regole

I gruppi di regole e le regole interne associate 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 la valutazione standard senza mostrare alcuna verifica, ma viene generato uno scoring del 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 delle condizioni

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

All'interno del runtime, sono accessibili le seguenti variabili di Fraud Defense:

Variabile	Tipo	Descrizione
`score`	`double`	Il punteggio bot di 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`).
`region_code`	`string`	Il codice regione CLDR Unicode (basato su ISO 3166-1 alpha-2) associato alla località della richiesta (ad esempio, `"US"`, `"CA"` o `"FR"`).
`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, consulta Bot.

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

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

Nelle policy di verifica 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", region_code == "US" 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 della policy di verifica di Fraud Defense:

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

Le funzioni di comprensione sono un tipo di macro integrato 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 delle regole di verifica

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

Verifica tutte le richieste con un punteggio basso

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

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

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

Contesta azioni specifiche con un punteggio basso

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

Configura 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 IP di Fraud Defense.

Non mostrare la verifica alla subnet di indirizzi IP

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

Non mostrare la verifica alle 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 verifica a un agente Google

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

Mostra la verifica 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, consulta Crea valutazioni per i siti web.