Eseguire l'integrazione con Google Cloud Armor per i siti web

Questo documento mostra come integrare reCAPTCHA per WAF con Google Cloud Armor sui siti web.

Per completare l'integrazione, devi implementare una o più funzionalità di reCAPTCHA per WAF e configurare i criteri di sicurezza di Google Cloud Armor.

Prima di iniziare

1. Abilita l'API reCAPTCHA Enterprise.

   Enable the API

2. Pianifica come implementare le funzionalità di reCAPTCHA per WAF per proteggere il tuo sito web.

   1. Scegli una o più funzionalità WAF che corrispondono meglio al tuo caso d'uso.
   2. Identifica le pagine che vuoi proteggere e il tipo di funzionalità WAF che vuoi implementare su queste pagine.

Implementare le funzionalità di reCAPTCHA per WAF

A seconda dei tuoi requisiti, puoi utilizzare una o più funzionalità di reCAPTCHA per WAF in un'unica applicazione.

Se vuoi utilizzare più di una funzionalità, devi creare una chiave reCAPTCHA per ciascuna di queste funzionalità e utilizzarle nella tua applicazione. Ad esempio, se vuoi utilizzare i token di azione reCAPTCHA e la pagina di verifica reCAPTCHA, devi creare una chiave per i token di azione e una chiave per la pagina di verifica e utilizzarle nella tua applicazione.

Implementa i token di azione reCAPTCHA

Per generare token di azione, devi avere reCAPTCHA in esecuzione nelle tue pagine web. Dopo che reCAPTCHA ha generato un token di azione, devi associarlo a un'intestazione di richiesta predefinita ogni volta che devi proteggere qualsiasi azione dell'utente, ad esempio checkout. Per impostazione predefinita, gli action-token sono validi per 30 minuti, ma possono variare in base al traffico. Devi allegare l'action-token a un'intestazione di richiesta predefinita prima della scadenza del token, in modo che Google Cloud Armor possa valutare gli attributi del token.

Per implementare un token di azione reCAPTCHA:

1. Crea una chiave del token di azione per il tuo sito web.

   console Cloud

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

      Vai a reCAPTCHA

   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 poi seleziona il progetto.

   3. Fai clic su Crea chiave.
   4. Nel campo Nome visualizzato, inserisci un nome visualizzato per la chiave.
   5. A seconda della piattaforma per cui vuoi creare le chiavi reCAPTCHA per WAF, esegui l'azione appropriata:
   1. Nel menu Scegli il tipo di piattaforma, seleziona Sito web.

      Viene visualizzata la sezione Elenco di domini.

   2. Inserisci il nome di dominio del tuo sito web:

      1. Nella sezione Elenco di domini, fai clic su Aggiungi un dominio.
      2. Nel campo Domain (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 un massimo di 250 domini.

         Per i siti web, la chiave reCAPTCHA è univoca per i domini e i sottodomini specificati. Puoi specificare più di un dominio se pubblichi il tuo sito web da più domini. Se specifichi un dominio (ad es. examplepetstore.com), non è necessario specificare i relativi sottodomini (ad es. subdomain.examplepetstore.com).

   3. Espandi la sezione Web application firewall (WAF), verifica del dominio, pagine AMP e richiesta di verifica.
      
   4. Attiva l'opzione di attivazione/disattivazione Web Application Firewall (WAF).
      

   5. Dal menu Funzionalità, seleziona Token di azione.

      

   6. (Facoltativo) Attiva Utilizza la verifica tramite casella di controllo.

   7. Fai clic su Crea chiave.

   La chiave appena creata è elencata nella pagina Chiavi reCAPTCHA.

   gcloud

   Per creare le chiavi reCAPTCHA, utilizza il comando gcloud recaptcha keys create.

   Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

   • DISPLAY_NAME: il nome della chiave. In genere, il nome di un sito.
   • INTEGRATION_TYPE: tipo di integrazione. Specifica score o checkbox.
   • DOMAIN_NAME: domini o sottodomini dei siti web autorizzati a utilizzare la chiave.

     Specifica più domini come elenco separato da virgole. (Facoltativo) Specifica --allow-all-domains per disattivare la verifica del dominio.

     La disattivazione della verifica del dominio comporta un rischio per la sicurezza perché non sono previste limitazioni sul sito, pertanto chiunque può accedere alla chiave reCAPTCHA e utilizzarla.

   • WAF_FEATURE: il nome della funzionalità WAF. Specifica action-token.
   • WAF_SERVICE: il nome del fornitore di servizi WAF. Specifica CA per Google Cloud Armor.

   Esegui il comando gcloud recaptcha keys create:

   Linux, macOS o Cloud Shell

   gcloud recaptcha keys create \
   --web \
   --display-name=DISPLAY_NAME  \
   --integration-type=INTEGRATION_TYPE \
   --domains=DOMAIN_NAME \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE

   Windows (PowerShell)

   gcloud recaptcha keys create `
   --web `
   --display-name=DISPLAY_NAME  `
   --integration-type=INTEGRATION_TYPE `
   --domains=DOMAIN_NAME `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE

   Windows (cmd.exe)

   gcloud recaptcha keys create ^
   --web ^
   --display-name=DISPLAY_NAME  ^
   --integration-type=INTEGRATION_TYPE ^
   --domains=DOMAIN_NAME ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE

   La risposta contiene la chiave reCAPTCHA appena creata.

   REST

   Per informazioni di riferimento dell'API sui tipi di token e sui tipi di integrazione, consulta Token e Tipo di integrazione.

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

   • DISPLAY_NAME: il nome della chiave. In genere, il nome di un sito.
   • INTEGRATION_TYPE: tipo di integrazione. Specifica score o checkbox.
   • DOMAIN_NAME: domini o sottodomini dei siti web autorizzati a utilizzare la chiave.

     Specifica più domini come elenco separato da virgole. (Facoltativo) Specifica --allow-all-domains per disattivare la verifica del dominio.

     La disattivazione della verifica del dominio comporta un rischio per la sicurezza perché non sono previste limitazioni sul sito, pertanto chiunque può accedere alla chiave reCAPTCHA e utilizzarla.

   • WAF_FEATURE: il nome della funzionalità WAF. Specifica action-token.
   • WAF_SERVICE: il nome del fornitore di servizi WAF. Specifica CA per Google Cloud Armor.

   Metodo HTTP e URL:

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

   Corpo JSON della richiesta:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
     
   "wafFeature": "WAF_FEATURE"
     }
     "webSettings": {
       "allowedDomains": "DOMAINS",
       "integrationType": "TYPE_OF_INTEGRATION"
      }
      
   }
   

   Per inviare la richiesta, scegli una delle seguenti opzioni:

   curl

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

   curl -X POST \
        -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"

   PowerShell

   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 POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

   Dovresti ricevere una risposta JSON simile alla seguente:

   
   {
     "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
    "integrationType": "SCORE",
   
   
   },
   "wafSettings": {
     "wafService": "CA",
   
     "wafFeature": "ACTION_TOKEN"
     
   
   }
   }
   
   

2. Integra il codice JavaScript di reCAPTCHA nelle tue pagine web con la chiave action-token che hai creato. Per le istruzioni, consulta il documento corrispondente al tipo di integrazione della chiave del token di azione.

   • Per il tipo di integrazione SCORE, consulta Integrare le chiavi basate su punteggi con il frontend.
   • Per il tipo di integrazione CHECKBOX, consulta Eseguire il rendering del widget reCAPTCHA sul frontend.

3. Dopo aver ricevuto il token da reCAPTCHA, allegalo a un 'intestazione di richiesta predefinita nel seguente formato:

    X-Recaptcha-Token: value-of-your-action-token
   

   Puoi utilizzare linguaggi come XHR, Ajax o l'API Fetch per allegare il token a un'intestazione di richiesta predefinita.

   Lo script di esempio seguente mostra come proteggere l'azione execute e allegare il token a un'intestazione di richiesta predefinita utilizzando JavaScript + XHR:

     
     <script>
       src="https://www.google.com/recaptcha/enterprise.js?render=ACTION_TOKEN_KEY"></script>
   
       <script>
       function onSuccess(action_token) {
            const xhr = new XMLHttpRequest();
            xhr.open('GET','YOUR_URL', false);
            // Attach the action-token to the predefined request header
            xhr.setRequestHeader("X-Recaptcha-Token", action_token);
            xhr.send(null);
          }
          function onError(reason) {
            alert('Response promise rejected: ' + reason);
          grecaptcha.enterprise.ready(function () {
            document.getElementById("execute-button").onclick = () => {
              grecaptcha.enterprise.execute('ACTION_TOKEN_KEY', {
              }).then(onSuccess, onError);
            };
          });
         }
       </script>
     
     

Implementare i token di sessione reCAPTCHA

Il codice JavaScript di reCAPTCHA imposta un token di sessione reCAPTCHA come cookie sul browser dell'utente finale dopo la valutazione. Il browser dell'utente finale allega il cookie e lo aggiorna finché il JavaScript di reCAPCHA rimane attivo.

Per fornire un token di sessione come cookie, installa una chiave per token di sessione in almeno una delle tue pagine web che soddisfi i seguenti requisiti:

• La pagina web deve essere la pagina visitata dall'utente finale prima della pagina che deve essere protetta. Ad esempio, se vuoi proteggere la pagina di pagamento, installa una chiave token di sessione nella home page o nella pagina del prodotto.
• La pagina web è protetta da un criterio di sicurezza di Google Cloud Armor.

Puoi utilizzare questo cookie per proteggere le richieste e i caricamenti di pagine successivi dell'utente finale su un dominio specifico. Per impostazione predefinita, i token di sessione sono validi per 30 minuti. Tuttavia, se l'utente finale rimane nella pagina in cui hai implementato il token di sessione, reCAPTCHA lo aggiorna periodicamente per impedirne la scadenza.

Installa i token di sessione in ogni pagina che deve essere protetta da reCAPTCHA. Ti consigliamo di proteggere ogni pagina con reCAPTCHA e di utilizzare le regole di Google Cloud Armor per applicare l'accesso a tutte le pagine, tranne la prima pagina visitata dagli utenti finali.

   recaptcha-ca-t=value-of-your-session-token;domain=domain;expires=expiration_time

Per implementare un token di sessione reCAPTCHA:

1. Crea una chiave per il token di sessione per il tuo sito web.

   console Cloud

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

      Vai a reCAPTCHA

   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 poi seleziona il progetto.

   3. Fai clic su Crea chiave.
   4. Nel campo Nome visualizzato, inserisci un nome visualizzato per la chiave.
   5. A seconda della piattaforma per cui vuoi creare le chiavi reCAPTCHA per WAF, esegui l'azione appropriata:
   1. Nel menu Scegli il tipo di piattaforma, seleziona Sito web.

      Viene visualizzata la sezione Elenco di domini.

   2. Inserisci il nome di dominio del tuo sito web:

      1. Nella sezione Elenco di domini, fai clic su Aggiungi un dominio.
      2. Nel campo Domain (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 un massimo di 250 domini.

         Per i siti web, la chiave reCAPTCHA è univoca per i domini e i sottodomini specificati. Puoi specificare più di un dominio se pubblichi il tuo sito web da più domini. Se specifichi un dominio (ad es. examplepetstore.com), non è necessario specificare i relativi sottodomini (ad es. subdomain.examplepetstore.com).

   3. Espandi la sezione Web application firewall (WAF), verifica del dominio, pagine AMP e richiesta di verifica.
      
   4. Attiva l'opzione di attivazione/disattivazione Web Application Firewall (WAF).
      

   5. Nel menu Funzionalità, seleziona Token sessione.

      
   6. (Facoltativo) Attiva Disattiva verifica dominio.

      La disattivazione della verifica del dominio comporta un rischio per la sicurezza perché non sono previste limitazioni sul sito, pertanto chiunque può accedere alla chiave reCAPTCHA e utilizzarla.

   7. Fai clic su Crea chiave.

   La chiave appena creata è elencata nella pagina Chiavi reCAPTCHA.

   gcloud

   Per creare le chiavi reCAPTCHA, utilizza il comando gcloud recaptcha keys create.

   Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

   • DISPLAY_NAME: il nome della chiave. In genere, il nome di un sito.
   • INTEGRATION_TYPE: tipo di integrazione. Specifica score.
   • DOMAIN_NAME: domini o sottodomini dei siti web autorizzati a utilizzare la chiave.

     Specifica più domini come elenco separato da virgole. (Facoltativo) Specifica --allow-all-domains per disattivare la verifica del dominio.

     La disattivazione della verifica del dominio comporta un rischio per la sicurezza perché non sono previste limitazioni sul sito, pertanto chiunque può accedere alla chiave reCAPTCHA e utilizzarla.

   • WAF_FEATURE: il nome della funzionalità WAF. Specifica session-token.
   • WAF_SERVICE: il nome del fornitore di servizi WAF. Specifica CA per Google Cloud Armor.

   Esegui il comando gcloud recaptcha keys create:

   Linux, macOS o Cloud Shell

   gcloud recaptcha keys create \
   --web \
   --display-name=DISPLAY_NAME  \
   --integration-type=INTEGRATION_TYPE \
   --domains=DOMAIN_NAME \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE

   Windows (PowerShell)

   gcloud recaptcha keys create `
   --web `
   --display-name=DISPLAY_NAME  `
   --integration-type=INTEGRATION_TYPE `
   --domains=DOMAIN_NAME `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE

   Windows (cmd.exe)

   gcloud recaptcha keys create ^
   --web ^
   --display-name=DISPLAY_NAME  ^
   --integration-type=INTEGRATION_TYPE ^
   --domains=DOMAIN_NAME ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE

   La risposta contiene la chiave reCAPTCHA appena creata.

   REST

   Per informazioni di riferimento dell'API sui tipi di token e sui tipi di integrazione, consulta Token e Tipo di integrazione.

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

   • DISPLAY_NAME: il nome della chiave. In genere, il nome di un sito.
   • INTEGRATION_TYPE: tipo di integrazione. Specifica score.
   • DOMAIN_NAME: domini o sottodomini dei siti web autorizzati a utilizzare la chiave.

     Specifica più domini come elenco separato da virgole. (Facoltativo) Specifica --allow-all-domains per disattivare la verifica del dominio.

     La disattivazione della verifica del dominio comporta un rischio per la sicurezza perché non sono previste limitazioni sul sito, pertanto chiunque può accedere alla chiave reCAPTCHA e utilizzarla.

   • WAF_FEATURE: il nome della funzionalità WAF. Specifica session-token.
   • WAF_SERVICE: il nome del fornitore di servizi WAF. Specifica CA per Google Cloud Armor.

   Metodo HTTP e URL:

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

   Corpo JSON della richiesta:

   
   {
     "displayName": "DISPLAY_NAME",
      'wafSettings': "  {
          "wafService": "WAF_SERVICE",
     
   "wafFeature": "WAF_FEATURE"
     }
     "webSettings": {
       "allowedDomains": "DOMAINS",
       "integrationType": "TYPE_OF_INTEGRATION"
      }
      
   }
   

   Per inviare la richiesta, scegli una delle seguenti opzioni:

   curl

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

   curl -X POST \
        -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"

   PowerShell

   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 POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

   Dovresti ricevere una risposta JSON simile alla seguente:

   
   {
     "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   
   "webSettings": {
     "allowAllDomains": true,
     "allowedDomains": [
       "localhost"
     ],
   
    "integrationType": "SCORE",
   
   
   },
   "wafSettings": {
     "wafService": "CA",
   
     "wafFeature": "SESSION_TOKEN"
   
   
   }
   }
   
   

2. Aggiungi la chiave session-token e waf=session al codice JavaScript di reCAPTCHA.

   Il seguente script di esempio mostra come implementare un token sessione in una pagina web:

   <!DOCTYPE html>
   <html lang="en">
   <head>
    <meta charset="UTF-8">
    <title>reCAPTCHA WAF Session Token</title>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=SESSION_TOKEN_KEY&waf=session" async defer></script>
    <body></body>
   </head>
   </html>

Implementare una pagina di verifica reCAPTCHA

Quando implementi una pagina di verifica reCAPTCHA, reCAPTCHA reindirizza a una pagina interpagina in cui viene stabilito se è necessario mostrare un test CAPTCHA a un utente. Pertanto, i test CAPTCHA potrebbero non essere visibili a tutti gli utenti.

Per implementare una pagina di verifica reCAPTCHA, crea una chiave per la pagina di verifica per il tuo sito web.

gcloud recaptcha keys create \
--web \
--display-name=DISPLAY_NAME  \
--integration-type=INTEGRATION_TYPE \
--domains=DOMAIN_NAME \
--waf-feature=WAF_FEATURE \
--waf-service=WAF_SERVICE

gcloud recaptcha keys create `
--web `
--display-name=DISPLAY_NAME  `
--integration-type=INTEGRATION_TYPE `
--domains=DOMAIN_NAME `
--waf-feature=WAF_FEATURE `
--waf-service=WAF_SERVICE

gcloud recaptcha keys create ^
--web ^
--display-name=DISPLAY_NAME  ^
--integration-type=INTEGRATION_TYPE ^
--domains=DOMAIN_NAME ^
--waf-feature=WAF_FEATURE ^
--waf-service=WAF_SERVICE

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

{
  "displayName": "DISPLAY_NAME",
   'wafSettings': "  {
       "wafService": "WAF_SERVICE",
  
"wafFeature": "WAF_FEATURE"
  }
  "webSettings": {
    "allowedDomains": "DOMAINS",
    "integrationType": "TYPE_OF_INTEGRATION"
   }
   
}

curl -X POST \
     -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"

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

{
  "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
"displayName": "DISPLAY_NAME,

"webSettings": {
  "allowAllDomains": true,
  "allowedDomains": [
    "localhost"
  ],

  "integrationType": "INVISIBLE",
 

},
"wafSettings": {
  "wafService": "CA",

  "wafFeature": "CHALLENGE_PAGE"
  

}
}

Configura i criteri di sicurezza di Google Cloud Armor

Dopo aver implementato le funzionalità di reCAPTCHA per WAF, devi configurare i criteri di sicurezza di Google Cloud Armor per la gestione dei bot.

Se hai implementato una pagina di verifica reCAPTCHA, devi svolgere quanto segue:

1. Associa la chiave della pagina di verifica al tuo criterio di sicurezza.
2. Configura una regola del criterio di sicurezza per reindirizzare una richiesta di valutazione reCAPTCHA.

Se hai implementato token di azione reCAPTCHA o token di sessione, devi configurare una regola del criterio di sicurezza che valuti i token reCAPTCHA.

Prima di configurare i criteri di sicurezza di Google Cloud Armor, comprendi gli attributi dei token reCAPTCHA per Google Cloud Armor.

Per scoprire come configurare i criteri di sicurezza di Google Cloud Armor e utilizzare le chiavi reCAPTCHA per WAF con i tuoi criteri di sicurezza, consulta Configurare le regole per la gestione dei bot.

Passaggi successivi

• Esempi di integrazione con Google Cloud Armor.
• Scopri come implementare le funzionalità WAF di reCAPTCHA con Google Cloud Armor.