Creazione di chiavi reCAPTCHA per i siti web

Questa pagina spiega come creare chiavi reCAPTCHA (note anche come chiavi) per verificare le interazioni degli utenti sulle tue pagine web.

Le chiavi reCAPTCHA rappresentano il modo in cui è configurato reCAPTCHA un sito web. La configurazione include opzioni importanti, ad esempio se mostrare o meno le verifiche CAPTCHA.

Prima di iniziare

• Prepara l'ambiente per reCAPTCHA.
• Assicurati di disporre del seguente ruolo Identity and Access Management: Amministratore di reCAPTCHA Enterprise (roles/recaptchaenterprise.admin)
• Scegli il tipo di chiave più adatto al tuo caso d'uso.

Crea una chiave reCAPTCHA

Non esiste alcun limite al numero di chiavi reCAPTCHA che puoi creare per un progetto Google Cloud. È meglio crearne uno Chiave reCAPTCHA per sito web.

Consigliamo di creare chiavi reCAPTCHA separate per la gestione temporanea e ambienti di produzione. In caso contrario, rischi di inquinare reCAPTCHA l'analisi del rischio con i dati dell'ambiente di test.

Il modo più semplice per creare una chiave reCAPTCHA è tramite Console di amministrazione di reCAPTCHA. In alternativa, puoi utilizzare la console Google Cloud, l'API reCAPTCHA Enterprise o Google Cloud CLI.

Console di amministrazione

1. Vai alla Console di amministrazione di reCAPTCHA.

   Vai alla console di amministrazione di reCAPTCHA

2. Nel campo Etichetta, inserisci un nome che consenta di identificare il sito.
3. Se vuoi creare una chiave basata su punteggio, seleziona In base al punteggio (v3). Se vuoi creare una chiave della casella di controllo, seleziona Sfida (v2).
4. Per aggiungere un dominio, inserisci il tuo nome e fai clic su .

   Per aggiungere un altro dominio, puoi ripetere questo passaggio. Puoi aggiungere fino a un massimo di 250 domini.

5. Se non hai mai utilizzato la console Google Cloud, leggi i Termini di servizio e seleziona la casella di controllo.
6. Fai clic su Invia.

Se non hai mai utilizzato la console Google Cloud, viene creato un progetto Google Cloud e vengono attivate le API necessarie per iniziare. Se hai già un progetto Google Cloud, le API necessarie sono abilitate per iniziare.

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

3. Fai clic su Crea chiave.
4. Nel campo Nome visualizzato, inserisci un nome visualizzato per la chiave.
5. Nel menu Scegli il tipo di piattaforma, seleziona Sito web.

   Viene visualizzata la sezione Elenco di domini.

6. Inserisci il nome di dominio per il 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 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 una dominio se pubblichi il sito web da più domini. Se specifichi un dominio (ad esempio examplepetstore.com), non devi specificarne i sottodomini (ad esempio, subdomain.examplepetstore.com).

      Per utilizzare una chiave su più di 250 domini, fai clic sull'opzione di attivazione/disattivazione Disattiva verifica dominio. reCAPTCHA ignorerà quindi l'elenco di domini. Devi eseguire la verifica del dominio autonomamente esaminando il tokenProperties.hostname campo nelle valutazioni che crei.

7. A seconda del tipo di chiave reCAPTCHA che vuoi creare per il tuo sito web, esegui l'azione appropriata:

Crea chiavi reCAPTCHA basate sul punteggio

Nota: la creazione di una chiave basata sul punteggio è l'opzione predefinita nella nella console Google Cloud.

1. (Facoltativo) Se vuoi disattivare la verifica del dominio o consentire le pagine AMP, espandi la sezione Web application firewall (WAF), verifica del dominio, pagine AMP e richiesta di verifica.
   
   1. Per proteggere la chiave reCAPTCHA per il tuo dominio e sottodomini, assicurati che l'opzione Disattiva verifica dominio sia disattivata.

      La disattivazione della verifica del dominio rappresenta un rischio per la sicurezza perché non sono limitazioni del sito, pertanto è possibile accedere alla chiave reCAPTCHA e utilizzarla da chiunque.

      
   2. Se vuoi consentire il funzionamento della chiave basata su punteggi con Accelerated Mobile Pages (AMP), attiva l'opzione di attivazione/disattivazione Consenti il funzionamento di questa chiave con le pagine AMP.

   3. Per il tuo ambiente non di produzione, se vuoi specificare un punteggio, devi far da restituire quando vengono create valutazioni:

      1. Fai clic sul pulsante di attivazione/disattivazione Questa è una chiave di test.
      2. Nella casella Punteggio, specifica un punteggio compreso tra 0 e 1,0.
      
   4. Fai clic su Crea chiave.

   La chiave appena creata è elencata nella pagina Chiavi reCAPTCHA.

Crea chiavi reCAPTCHA della casella di controllo

Non è consigliabile utilizzare le chiavi delle caselle di controllo perché aumentano la complessità per l'utente e non migliorano in modo significativo l'accuratezza.

1. Espandi la sezione Web application firewall (WAF), verifica del dominio, pagine AMP e richiesta di verifica.
   
2. Per proteggere la chiave reCAPTCHA per il tuo dominio e i tuoi sottodomini, assicurati che l'opzione di attivazione/disattivazione Disattiva la verifica del dominio sia disattivata.

   La disattivazione della verifica del dominio rappresenta un rischio per la sicurezza perché non sono limitazioni del sito, pertanto è possibile accedere alla chiave reCAPTCHA e utilizzarla da chiunque.

   
3. Attiva l'opzione Utilizza la verifica tramite casella di controllo.
   
4. Seleziona l'opzione Sfida la sicurezza appropriata.

   L'opzione di sicurezza della verifica controlla la probabilità che a un utente venga richiesta una verifica secondaria in cui gli viene chiesto di selezionare le immagini in base a una categoria identificata (ad esempio, seleziona le immagini con una motocicletta o le scale).

   

   Se vuoi assicurarti la migliore protezione antifrode, seleziona Massima difficoltà (maggiore protezione dai bot).

   Se selezioni Verifica con difficoltà minima, è meno probabile che agli utenti venga richiesta la verifica visiva.

5. Per il tuo ambiente non di produzione, se vuoi specificare un punteggio, devi far da restituire quando vengono create valutazioni:

   1. Fai clic sul pulsante di attivazione/disattivazione Questa è una chiave di test.
   2. Nella casella Punteggio, specifica un punteggio compreso tra 0 e 1,0.
   3. Seleziona l'opzione Tipo di sfida appropriata.
      • A volte la verifica viene visualizzata Automatica.
      • Nessun CAPTCHA non mostra un test.
      • Sfida non risolvibile mostra le immagini, ma la sfida non è stata superata.
      
   4. 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 uno qualsiasi dei dati di comando 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. A seconda del tipo di chiavi, specifica i seguenti valori:
  • score per le chiavi basate sul punteggio.
  • checkbox per le chiavi delle caselle di controllo.
  Nota: sconsigliamo di utilizzare CHECKBOX perché aumenta la complessità per l'utente e non migliora in modo significativo l'accuratezza. Per ulteriori informazioni, consulta le Domande frequenti.
• DOMAIN_NAME: domini o sottodomini dei siti web autorizzati a utilizzare la chiave.

  Specifica più domini come elenco separato da virgole.

  Per utilizzare una chiave su più di 250 domini, specifica --allow-all-domains per disattivare la verifica del dominio. reCAPTCHA ignorerà quindi l'elenco di domini. Devi eseguire la verifica del dominio autonomamente esaminando il tokenProperties.hostname campo nelle valutazioni che crei.

  La disattivazione della verifica del dominio rappresenta un rischio per la sicurezza perché non sono limitazioni del sito, pertanto è possibile accedere alla chiave reCAPTCHA e utilizzarla da chiunque.

  Nota: La chiave reCAPTCHA è univoca per i domini e nei sottodomini da te specificati. Puoi specificare più di un dominio se pubblicare il sito web da più domini. Se specifichi un dominio (ad esempio examplepetstore.com), non devi specificare i relativi sottodomini (ad esempio subdomain.examplepetstore.com).

Esegui la 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

Windows (PowerShell)

gcloud recaptcha keys create `
        --web `
        --display-name=DISPLAY_NAME  `
        --integration-type=INTEGRATION_TYPE `
        --domains=DOMAIN_NAME

Windows (cmd.exe)

gcloud recaptcha keys create ^
        --web ^
        --display-name=DISPLAY_NAME  ^
        --integration-type=INTEGRATION_TYPE ^
        --domains=DOMAIN_NAME

La risposta contiene la chiave reCAPTCHA appena creata.

REST

Per informazioni di riferimento dell'API su tipi di chiavi e tipi di integrazione, vedi Chiave e Integration type (Tipo di integrazione).

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

• DISPLAY_NAME: nome della chiave. In genere il nome di un sito.
• INTEGRATION_TYPE: tipo di integrazione. A seconda del tipo di chiavi, specifica i seguenti valori:
  • score per le chiavi basate sul punteggio.
  • checkbox per le chiavi delle caselle di controllo.
  di Gemini Advanced.
  Nota: sconsigliamo di utilizzare CHECKBOX perché aumenta le difficoltà per l'utente e non ne migliorano significativamente la precisione. Per ulteriori informazioni, consulta le Domande frequenti.
• DOMAIN_NAME: domini o sottodomini dei siti web autorizzati a utilizzare la chiave.

  Specifica più domini come elenco separato da virgole.

  Per utilizzare una chiave su più di 250 domini, specifica --allow-all-domains per disattivare la verifica del dominio. reCAPTCHA ignorerà quindi l'elenco di domini. Devi eseguire personalmente la verifica del dominio esaminando le tokenProperties.hostname nelle valutazioni create.

  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.

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

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

{
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowedDomains": "DOMAINS",
    "integrationType": "TYPE_OF_INTEGRATION"
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

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 ti 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. ed esegui questo comando:

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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI 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. ed esegui questo comando:

$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/6Ldqgs0UAAAAAIn4k7YxEB-LwEh5S9-Gv6IIWB8m",
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowAllDomains": false,
    "allowedDomains": [
      DOMAINS
    ],
    "allowAmpTraffic": false,
    "integrationType": "SCORE",
    "challengeSecurityPreference": "CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED"
  }
}

Nota: dopo aver creato le chiavi reCAPTCHA, puoi modificarle o eliminarle. Non puoi recuperare le chiavi eliminate. Inoltre, non puoi eseguire la migrazione delle chiavi reCAPTCHA da un progetto Google Cloud a un altro.

(Facoltativo) Trovare una chiave secret reCAPTCHA legacy

Se vuoi eseguire l'integrazione con un'applicazione di terze parti che non utilizza l'API reCAPTCHA Enterprise, devi disporre della chiave segreta precedente.

Per ogni chiave di sito che crei, reCAPTCHA crea una chiave segreta reCAPTCHA legacy (chiave segreta legacy), che puoi utilizzare con la tua applicazione di terze parti.

Nota: sconsigliamo di utilizzare una chiave segreta precedente sul frontend perché saranno visibili ai tuoi utenti e i malintenzionati potrebbero utilizzare in modo illecito la tua applicazione.

Per trovare la chiave segreta precedente:

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

   Vai a reCAPTCHA

2. Nella sezione Chiavi reCAPTCHA, individua la chiave reCAPTCHA che hai creato e fai clic sulla chiave.

   

3. Nella pagina Dettagli della chiave, fai clic su Utilizza chiave precedente nella scheda Integrazione. Si apre una finestra di dialogo con le istruzioni su come utilizzare la chiave segreta precedente.

   

Passaggi successivi

• Installa chiavi basate sul punteggio nelle tue pagine web.
• Installa le chiavi delle caselle di controllo nelle pagine web.