Configurare Policy Engine con una chiave universale

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questo documento descrive come configurare Policy Engine sul tuo sito web utilizzando una chiave universale. La chiave universale è una nuova chiave di Google Cloud Fraud Defense che supporta la creazione di regole all'interno di Policy Engine.

Con Policy Engine, Fraud Defense può attivare in modo deterministico le verifiche CAPTCHA in base alle regole di policy personalizzate che configuri. Queste regole potrebbero decidere quando mostrare una verifica di Fraud Defense in base ai punteggi di rischio, agli indirizzi IP, agli user agent, agli ASN o alle identità dei bot verificati (agenti AI).

La configurazione di Policy Engine di Fraud Defense offre due funzionalità principali:

• Integrazione AutoExecute (protected_endpoint_group): semplifica l'integrazione di JavaScript frontend ispezionando automaticamente le richieste di rete asincrone in uscita e allegando i token reCAPTCHA, in modo che sia necessario solo un tag di script nel frontend.
• Policy di verifica (challenge_rule_groups): determina se mostrare una verifica per diverse azioni dell'utente e configura i livelli di difficoltà della verifica associati (USABILITY, BALANCE, SECURITY) utilizzando regole personalizzate basate su CEL.

Prima di iniziare

1. Prepara l'ambiente per reCAPTCHA.

2. Verifica che la fatturazione sia attivata per il tuo Google Cloud progetto.

   Per utilizzare Policy Engine, è necessario che la fatturazione sia collegata e abilitata nel progetto per Fraud Defense. Puoi abilitare la fatturazione utilizzando una carta di credito o un ID di fatturazione del progetto esistente Google Cloud . Se hai bisogno di aiuto con la fatturazione, contatta l'assistenza per la fatturazione Cloud.

Crea una chiave universale

A seconda dell'interfaccia che preferisci, scegli l'opzione appropriata per creare una chiave universale:

Console

1. Nella Google Cloud console, vai alla pagina reCAPTCHA.

   Vai a reCAPTCHA

2. Verifica che il nome del tuo progetto venga visualizzato nel selettore di risorse nella parte superiore della pagina.

   Se non vedi il nome del tuo progetto, fai clic sul selettore di risorse, quindi seleziona il progetto.

3. Seleziona la scheda Chiavi.
4. Fai clic su Crea chiave.
5. Nel campo Nome visualizzato, inserisci un nome visualizzato per la chiave.
6. Per Tipo di applicazione, seleziona Universale.
7. Fai clic su Crea chiave.

La chiave appena creata è elencata nella pagina Chiavi reCAPTCHA.

gcloud

Per creare una chiave universale utilizzando Google Cloud CLI, utilizza il gcloud recaptcha keys create comando con il --universal flag:

gcloud recaptcha keys create --universal --display-name=DISPLAY_NAME

La risposta contiene la chiave universale reCAPTCHA appena creata.

API REST

Per creare una chiave universale utilizzando l'API REST, utilizza il projects.keys.create metodo e specifica universalSettings:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

{
  "displayName": "DISPLAY_NAME",
  "universalSettings": {}
}

Sostituisci quanto segue:

• PROJECT_ID: il tuo Google Cloud ID progetto
• DISPLAY_NAME: un nome visualizzato per la chiave, in genere il nome del sito web

La risposta contiene la chiave universale reCAPTCHA appena creata.

Configura i domini per Policy Engine

Nota: per i siti web, la chiave reCAPTCHA è univoca per i domini e i sottodomini che specifichi. Puoi specificare più di un dominio se il tuo sito web viene pubblicato da più domini. Se specifichi un dominio (ad esempio, examplepetstore.com), non devi specificare i relativi sottodomini (ad esempio, subdomain.examplepetstore.com).

A seconda dell'interfaccia che preferisci, scegli l'opzione appropriata per configurare i domini consentiti per la chiave universale:

Console

1. Nella Google Cloud console, vai alla pagina **Fraud Defense**.

   Vai a Fraud Defense

2. Verifica che il nome del tuo progetto venga visualizzato nel selettore di risorse nella parte superiore della pagina.

   Se non vedi il nome del tuo progetto, fai clic sul selettore di risorse, quindi seleziona il progetto.

3. Fai clic sulla scheda Chiavi reCAPTCHA.

4. Identifica la chiave universale che vuoi configurare e fai clic sulla chiave.

5. Nella pagina Dettagli chiave, fai clic su Modifica chiave.

6. Identifica la sezione Impostazioni di utilizzo della chiave.

   Per proteggere la chiave reCAPTCHA per il tuo dominio e i tuoi sottodomini, assicurati che l'opzione Disattiva verifica del dominio sia disattivata.

   La disattivazione della verifica del dominio comporta un rischio per la sicurezza perché non ci sono restrizioni sul sito, quindi chiunque può accedere e utilizzare la chiave reCAPTCHA.

   Inserisci il nome di dominio del tuo sito web:

   1. Nella sezione Elenco domini, fai clic su Aggiungi un dominio.
   2. Nel campo Dominio, inserisci il nome del tuo dominio.
   3. (Facoltativo) Per aggiungere un altro dominio, fai clic su Aggiungi un dominio e inserisci il nome di un altro dominio nel campo Dominio. Puoi aggiungere fino a 250 domini.

7. Fai clic su Salva modifiche.

Nota: per utilizzare una policy su più di 250 domini, fai clic sull'opzione Disattiva verifica del dominio. Quando la verifica del dominio è disattivata, Fraud Defense ignora l'elenco dei domini e devi eseguire tu la verifica del dominio esaminando il tokenProperties.hostname campo nelle valutazioni che crei.

gcloud

Per aggiornare i domini consentiti per la chiave universale utilizzando Google Cloud CLI, utilizza il gcloud alpha recaptcha policies update comando e specifica i domini in un file di configurazione della policy (ad esempio, POLICY.yaml):

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

Nota: il comando gcloud alpha recaptcha policies update aggiorna l'intera policy. Qualsiasi protected_endpoint_group o challenge_rule_groups esistente deve essere incluso nel file POLICY.yaml per evitare di eliminarlo.

Il file POLICY.yaml deve specificare i domini consentiti in clientSettings:

clientSettings:
  allowedDomains:
    - DOMAIN_NAME_1
    - DOMAIN_NAME_2

In alternativa, per consentire tutti i domini e disattivare la verifica del dominio, imposta allowAllDomains su true nel file POLICY.yaml:

clientSettings:
  allowAllDomains: true

Sostituisci quanto segue:

• KEY_ID: l'ID o il nome della risorsa completo della chiave universale
• DOMAIN_NAME_1, DOMAIN_NAME_2: i nomi di dominio dei siti web autorizzati a utilizzare la chiave

Nota: quando allowAllDomains è impostato su true, Fraud Defense ignora l'elenco dei domini e devi eseguire tu la verifica del dominio esaminando il tokenProperties.hostname campo nelle valutazioni che crei.

API REST

Per aggiornare i domini consentiti per la chiave universale utilizzando l'API REST, utilizza il projects.keys.updatePolicy metodo.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

• PROJECT_ID: l'ID del tuo Google Cloud progetto
• KEY_ID: l'ID della tua chiave universale
• DOMAIN_NAME_1, DOMAIN_NAME_2: i nomi di dominio dei siti web autorizzati a utilizzare la chiave

Metodo HTTP e URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains

Corpo JSON della richiesta:

{
"clientSettings": {
  "allowedDomains": [
    "DOMAIN_NAME_1",
    "DOMAIN_NAME_2"
  ],
  "allowAllDomains": false
}
}

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains"

PowerShell (Windows)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, e quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains" | Select-Object -Expand Content

Se la richiesta va a buon fine, restituisce la configurazione della policy aggiornata.

Nota: per utilizzare una policy su più di 250 domini, imposta allowAllDomains su true nel corpo della richiesta. Quando allowAllDomains è impostato su true, Fraud Defense ignora l'elenco dei domini e devi eseguire tu la verifica del dominio esaminando il tokenProperties.hostname campo nelle valutazioni che crei.

Passaggi successivi

• Installa le chiavi universali nelle pagine web.