Integrare reCAPTCHA per WAF con Cloudflare

action-token

Per generare token di azione, devi aver eseguito reCAPTCHA nelle tue pagine web. Dopo che reCAPTCHA genera un token di azione, lo colleghi a un'intestazione della richiesta predefinita ovunque tu debba proteggere un'azione dell'utente, ad esempio checkout. Per impostazione predefinita, i token di azione sono validi per 30 minuti, ma possono variare a seconda del traffico. Devi allegare il token di azione a un'intestazione della richiesta predefinita prima della scadenza del token, in modo che Cloudflare possa valutare gli attributi del token.

Per implementare un token di azione reCAPTCHA:

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

   gcloud

   Per creare 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: i domini o i 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 è un rischio per la sicurezza perché non ci sono restrizioni sul sito, quindi chiunque può accedere e utilizzare la chiave reCAPTCHA.

   • WAF_FEATURE: il nome della funzionalità WAF. Specifica action-token.
   • WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica cloudflare per Cloudflare.

   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 sull'API relative ai tipi di chiavi e di integrazione, vedi Key e Integration type.

   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: i domini o i 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 è un rischio per la sicurezza perché non ci sono restrizioni sul sito, quindi chiunque può accedere e utilizzare la chiave reCAPTCHA.

   • WAF_FEATURE: il nome della funzionalità WAF. Specifica action-token.
   • WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica cloudflare per Cloudflare.

   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 di queste 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": "cloudflare",
   
     "wafFeature": "ACTION_TOKEN"
     
   
   }
   }
   
   

   Registra la chiave del token di azione per utilizzarla in un secondo momento.

2. Integra JavaScript reCAPTCHA nelle tue pagine web con la chiave del token di azione che hai creato. Per istruzioni, consulta il documento corrispondente al tipo di integrazione della chiave del token di azione.
   • Per il tipo di integrazione SCORE, vedi Integrare le chiavi basate sul punteggio con il frontend.
   • Per il tipo di integrazione CHECKBOX, consulta Visualizzare il widget reCAPTCHA nel frontend.
3. Dopo aver ricevuto il token da reCAPTCHA, allegalo a un'intestazione della richiesta predefinita nel seguente formato:

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

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

   Il seguente script di esempio mostra come proteggere l'azione execute e allegare il token a un'intestazione della 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>
     
     

session-token

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

Per fornire un token di sessione come cookie, installa una chiave del token di sessione in almeno una delle tue pagine web che l'utente finale visita prima della pagina da proteggere. Ad esempio, se vuoi proteggere la pagina di pagamento, installa una chiave del token di sessione nella home page o nella pagina di prodotto.

Puoi includere il codice JavaScript di reCAPTCHA nelle tue pagine web configurando il file wrangler.toml durante l'installazione del pacchetto reCAPTCHA per Cloudflare oppure installare la chiave di sessione nelle tue pagine web. L'inclusione di reCAPTCHA JavaScript da Cloudflare integra reCAPTCHA utilizzando la chiave del token di sessione senza la necessità di installare manualmente le chiavi nelle tue pagine web.

Puoi utilizzare questo cookie per proteggere le richieste successive e i caricamenti di pagina dell'utente finale su un dominio specifico. I token di sessione sono validi per 30 minuti per impostazione predefinita. Tuttavia, se l'utente finale rimane sulla pagina in cui hai implementato il token di sessione, reCAPTCHA aggiorna periodicamente il token di sessione 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, ad eccezione della prima pagina che gli utenti finali visitano.

   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 token di sessione per il tuo sito web.

   gcloud

   Per creare 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: i domini o i 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 è un rischio per la sicurezza perché non ci sono restrizioni sul sito, quindi chiunque può accedere e utilizzare la chiave reCAPTCHA.

   • WAF_FEATURE: il nome della funzionalità WAF. Specifica session-token.
   • WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica cloudflare per Cloudflare.

   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 sull'API relative ai tipi di chiavi e di integrazione, vedi Key e Integration type.

   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: i domini o i 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 è un rischio per la sicurezza perché non ci sono restrizioni sul sito, quindi chiunque può accedere e utilizzare la chiave reCAPTCHA.

   • WAF_FEATURE: il nome della funzionalità WAF. Specifica session-token.
   • WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica cloudflare per Cloudflare.

   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 di queste 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": "cloudflare",
   
     "wafFeature": "SESSION_TOKEN"
   
   
   }
   }
   
   

   Registra la chiave del token di sessione per utilizzarla in un secondo momento.

   Se vuoi inserire il JavaScript di reCAPTCHA da Cloudflare, salta il passaggio successivo e configura wranger.toml.

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

   Il seguente script di esempio mostra come implementare un token di 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>

challenge-page

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

Per implementare una pagina di verifica reCAPTCHA:

1. Crea una chiave della pagina di verifica per il tuo sito web.

   gcloud

   Per creare 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 invisible.
   • DOMAIN_NAME: i domini o i sottodomini dei siti web autorizzati a utilizzare la chiave. Specifica --allow-all-domains.
   • WAF_FEATURE: il nome della funzionalità WAF. Specifica challenge-page.
   • WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica cloudflare per Cloudflare.

   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 sull'API relative ai tipi di chiavi e di integrazione, vedi Key e Integration type.

   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 invisible.
   • DOMAIN_NAME: i domini o i sottodomini dei siti web autorizzati a utilizzare la chiave. Specifica --allow-all-domains.
   • WAF_FEATURE: il nome della funzionalità WAF. Specifica challenge-page.
   • WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica cloudflare per Cloudflare.

   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 di queste 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": "INVISIBLE",
    
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
   
     "wafFeature": "CHALLENGE_PAGE"
     
   
   }
   }
   
   

   Registra la chiave della pagina della sfida per utilizzarla in un secondo momento.

2. Per reindirizzare gli utenti alla pagina della richiesta di verifica reCAPTCHA e ricevere un token reCAPTCHA, crea una policy firewall con l'azione redirect sulle pagine protette.

Express

Per implementare reCAPTCHA express, crea una chiave express.

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. gcloud

   Per creare 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.
   • WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica cloudflare per Cloudflare.

   Esegui il comando gcloud recaptcha keys create:

   Linux, macOS o Cloud Shell

   gcloud recaptcha keys create \
   --express \
   --display-name=DISPLAY_NAME  \
   --waf-service=WAF_SERVICE

   Windows (PowerShell)

   gcloud recaptcha keys create `
   --express `
   --display-name=DISPLAY_NAME  `
   --waf-service=WAF_SERVICE

   Windows (cmd.exe)

   gcloud recaptcha keys create ^
   --express ^
   --display-name=DISPLAY_NAME  ^
   --waf-service=WAF_SERVICE

   La risposta contiene la chiave reCAPTCHA appena creata.

   REST

   Per informazioni di riferimento sull'API relative ai tipi di chiavi e di integrazione, vedi Key e Integration type.

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

   • DISPLAY_NAME: il nome della chiave. In genere il nome di un sito.
   • WAF_SERVICE: Nome del fornitore di servizi WAF. Specifica cloudflare per Cloudflare.

   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",
     
   }
   

   Per inviare la richiesta, scegli una di queste 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,
   
   },
   "wafSettings": {
     "wafService": "cloudflare",
   
     
   
   }
   }
   
   

   Registra la chiave rapida per utilizzarla in un secondo momento.