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 di Google Cloud Fraud Defense esistente.

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 punteggi di rischio, indirizzi IP, user agent, ASN, regioni geografiche o identità di bot verificati (agenti AI).

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

Configurazione 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 verifiche:
- Verifiche visive: chiedi agli utenti di selezionare le immagini in base a un prompt. Per impostazione predefinita, viene selezionata una verifica visiva quando una regola viene configurata con l'opzione di verifica selezionata.
- Verifiche audio: chiedi agli utenti di identificare i segnali audio parlati come alternativa di accessibilità.
- Verifiche con codice QR: chiedi agli utenti di scansionare un codice QR con il proprio dispositivo mobile per risolvere una verifica. Per utilizzare questa funzionalità, la chiave universale deve essere inclusa in una lista consentita. Per aggiungere la chiave universale alla lista consentita, contatta il team di Fraud Defense all'indirizzo fraud-defense@google.com e fornisci la chiave universale.

Prima di iniziare

Prepara l'ambiente per Google Cloud Fraud Defense.
Verifica che la fatturazione sia attivata per il tuo Google Cloud progetto. Puoi attivare la fatturazione utilizzando una carta di credito o un ID di fatturazione del 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, vedi Creare 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 Google Cloud console:
  1. Nella Google Cloud console, 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 projects.keys.list metodo.
- Per copiare l'ID di una chiave esistente utilizzando gcloud CLI, esegui il gcloud recaptcha keys list comando.
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 di configurazione generali, vedi Installare le chiavi universali sui siti web.

Panoramica della configurazione delle policy di Fraud Defense

La configurazione delle 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 delle policy utilizzando la Google Cloud console, gcloud CLI o l'API REST di reCAPTCHA Enterprise.

Console

Per visualizzare o aggiornare la configurazione delle policy nella Google Cloud console:

Nella Google Cloud console, vai alla pagina Fraud Defense.

Vai a Fraud Defense
Assicurati che il tuo progetto sia selezionato nel selettore di 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 delle condizioni.
Fai clic su Salva.

gcloud

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

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

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

gcloud alpha recaptcha policies describe --key=KEY_ID

API REST

Per aggiornare la configurazione delle policy per una chiave, chiama il projects.keys.updatePolicy metodo:

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 delle policy corrente per una chiave, chiama il projects.keys.getPolicy metodo:

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, vedi Esempi di configurazioni di regole di verifica.

Configurare le policy di verifica

Configura le policy di verifica all'interno della sezione challenge_rule_groups della configurazione delle 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 delle 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 e uno di essi 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 il test standard senza visualizzare alcuna verifica, ma viene generato un punteggio di rischio per la richiesta.

Livelli di difficoltà delle verifiche

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

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, inclusi operatori relazionali (<, <=, >, >=, ==, !=), aritmetici (+, -, /, *, %), logici (!, &&, ||) e di contenitore ([], 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 (ad esempio 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 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 Unicode CLDR (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, 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 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 condizioni valide che restituiscono un valore booleano. Tieni presente che, poiché user_asn è un tipo 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`	Verifica 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`	Verifica 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 uno stile di macro integrato in CEL. Sono disponibili le seguenti comprensioni:

Nome	Firma	Descrizione	Esempio
`has`	`has(message.field) -> bool`	Verifica se un campo è disponibile.	`has(verified_bots[0].name)`
`all`	`list(A).all(A, predicate(A) -> bool) -> bool`	Verifica se tutti gli elementi `x` in 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 configurazioni di regole di verifica valide.

Attivare la verifica per tutte le richieste con un punteggio basso

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

Selezionare una verifica ad alta frizione per tutte le richieste con un punteggio basso

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

Attivare la verifica per azioni specifiche con un punteggio basso

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

Configurare soglie di 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 inclusi 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à delle liste consentite di indirizzi IP di 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 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: {}

Mostrare 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, vedi Creare valutazioni per i siti web.