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

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

• Integrazione AutoExecute (protected_endpoint_group): semplifica l'integrazione di JavaScript nel frontend ispezionando automaticamente le richieste di rete asincrone in uscita e allegando i token reCAPTCHA, in modo che nel frontend sia necessario solo un tag di script.
• Policy di verifica (challenge_rule_groups): determina se mostrare una verifica in diverse azioni utente e configura i livelli di difficoltà della verifica 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 .

   Per utilizzare Policy Engine, è necessario un account di fatturazione collegato e abilitato. Puoi attivare la fatturazione utilizzando una carta di credito o un ID fatturazione del progetto Google Cloud esistente. 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 console Google Cloud , vai alla pagina Google Cloud Fraud Defense.

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

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

La risposta contiene la chiave 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 ID progetto Google Cloud
• DISPLAY_NAME: un nome visualizzato per la chiave, in genere il nome del tuo sito web

La risposta contiene la chiave 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 pubblichi il tuo sito web da più domini. Se specifichi un dominio (ad esempio examplepetstore.com), non è necessario 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 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 progetto, fai clic sul selettore di risorse e seleziona il progetto.

3. Fai clic sulla scheda Chiavi.

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 la verifica del dominio sia disattivata.

   La disattivazione della verifica del dominio rappresenta un rischio per la sicurezza perché non esistono restrizioni sul sito, pertanto la chiave reCAPTCHA può essere consultata e utilizzata da chiunque.

   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 sul pulsante di attivazione/disattivazione Disattiva la 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 chiave universale utilizzando Google Cloud CLI, utilizza il comando gcloud alpha recaptcha policies update 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. Tutti i protected_endpoint_group o challenge_rule_groups esistenti devono essere inclusi nel file POLICY.yaml per evitare di eliminarli.

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 tu la verifica del dominio esaminando il campo tokenProperties.hostname nelle valutazioni che crei.

API REST

Per aggiornare i domini consentiti per la 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 ID progetto Google Cloud
• KEY_ID: l'ID della 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 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 campo tokenProperties.hostname nelle valutazioni che crei.

Passaggi successivi

• Installa le chiavi universali sulle pagine web.