Creare 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 la configurazione di reCAPTCHA per 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 di Identity and Access Management: Amministratore 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. È preferibile creare una chiave reCAPTCHA per sito web.

Ti consigliamo di creare chiavi reCAPTCHA separate per gli ambienti di gestione temporanea e di produzione. In caso contrario, rischi di inquinare l'analisi dei rischi di reCAPTCHA con i dati del tuo ambiente di test.

Il modo più semplice per creare una chiave reCAPTCHA è tramite la Console di amministrazione 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 puoi utilizzare per identificare il tuo sito.
3. Se vuoi creare una chiave basata su punteggio, seleziona In base al punteggio (v3). Se vuoi creare una chiave con casella di controllo, seleziona Sfida (v2).
4. Per aggiungere un dominio, inserisci il nome del dominio 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 e poi seleziona il 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 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).

      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:

Creare chiavi reCAPTCHA basate sul punteggio

Nota: la creazione di una chiave basata su punteggi è l'opzione predefinita 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 i tuoi sottodomini, assicurati che l'opzione di attivazione/disattivazione Disattiva la verifica del dominio sia disattivata.

      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.

      
   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 l'ambiente non di produzione, se vuoi specificare un punteggio che la chiave deve restituire quando vengono create valutazioni, procedi nel seguente modo:

      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.

Creare chiavi reCAPTCHA per le caselle 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 comporta un rischio per la sicurezza perché non ci sono limitazioni sul sito, pertanto chiunque può accedere alla chiave reCAPTCHA e utilizzarla.

   
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 l'ambiente non di produzione, se vuoi specificare un punteggio che la chiave deve restituire quando vengono create valutazioni, procedi nel seguente modo:

   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 sfida viene visualizzata in Auto.
      • Nessun CAPTCHA non mostra una verifica.
      • Verifica irrisolvibile mostra le immagini, ma la verifica non viene 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 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. 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 comporta un rischio per la sicurezza perché non ci sono 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).

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

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 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. 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 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, 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

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, 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/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: non consigliamo di utilizzare una chiave segreta precedente nel frontend perché sarà visibile agli utenti e gli utenti malintenzionati possono abusare della 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. Viene visualizzata 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 tue pagine web.