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 del motore delle policy.

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

La configurazione del motore delle norme di difesa dalle frodi fornisce due funzionalità principali:

• Integrazione AutoExecute (protected_endpoint_group): semplifica l'integrazione JavaScript frontend is automatically inspected for outgoing asynchronous network requests and attaching reCAPTCHA tokens to them, so that only a tag di script is needed on your frontend.
• Norme relative alle sfide (challenge_rule_groups): determina se mostrare una sfida in diverse azioni dell'utente e configura i livelli di difficoltà della sfida associati (USABILITY, BALANCE, SECURITY) utilizzando regole personalizzate basate su CEL.

Prima di iniziare

1. Prepara il tuo ambiente per Google Cloud Fraud Defense.

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

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

Creare una chiave universale

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

Console

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

   Vai a Google Cloud 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, poi seleziona il tuo 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 comando gcloud recaptcha keys create con il flag --universal:

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

La risposta contiene la chiave reCAPTCHA universale appena creata.

API REST

Per creare una chiave universale utilizzando l'API REST, utilizza il metodo projects.keys.create 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 tuo sito web

La risposta contiene la chiave reCAPTCHA universale 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 specificarne i sottodomini (ad esempio, subdomain.examplepetstore.com).

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

Console

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

   Vai a Fraud Defense

2. Verifica che il nome del 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 e poi seleziona il tuo 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. Individua la sezione Impostazioni di utilizzo delle chiavi.

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

   La disattivazione della verifica del dominio è 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 un criterio su più di 250 domini, fai clic sul pulsante di attivazione/disattivazione Disattiva verifica del dominio. Quando la verifica del dominio è disabilitata, Fraud Defense ignora l'elenco dei domini e devi eseguire tu la verifica del dominio esaminando il campo tokenProperties.hostname nelle valutazioni che crei.

gcloud

Per aggiornare i domini consentiti per la tua chiave universale utilizzando Google Cloud CLI, utilizza il comando gcloud alpha recaptcha policies update e specifica i domini in un file di configurazione delle 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 norma. 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 completo della risorsa 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 la verifica del dominio autonomamente esaminando il campo tokenProperties.hostname nelle valutazioni che crei.

API REST

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

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

• PROJECT_ID: il tuo Google Cloud ID 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, 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 l'operazione ha esito positivo, la richiesta restituisce la configurazione della policy aggiornata.

Nota: per utilizzare un criterio 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 campo tokenProperties.hostname nelle valutazioni che crei.

Passaggi successivi

• Installare le chiavi universali sulle pagine web.