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 le verifiche CAPTCHA.

Prima di iniziare

• Prepara l'ambiente per reCAPTCHA.
• Assicurati di avere il 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 un limite al numero di chiavi reCAPTCHA che puoi creare per un Google Cloud progetto. È consigliabile creare una chiave reCAPTCHA per ogni sito web.

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

Il modo più semplice per creare una chiave reCAPTCHA è tramite la console di amministrazione di reCAPTCHA. In alternativa, puoi utilizzare la Google Cloud console, 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 sul punteggio, seleziona In base al punteggio (v3). Se vuoi creare una chiave della casella di controllo, seleziona Verifica (v2).
4. Per aggiungere un dominio, inserisci il nome di dominio e fai clic su .

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

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

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

console Cloud

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

   Vai a reCAPTCHA

2. Verifica che il nome del tuo 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 tuo 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 Web.

   Viene visualizzata la sezione Elenco domini.

7. Per proteggere la chiave reCAPTCHA per il tuo dominio e i tuoi sottodomini, assicurati che il pulsante Disattiva verifica dominio sia disattivato.

   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 tua chiave reCAPTCHA.

8. 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 un massimo di 250 domini.

      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 devi specificare i relativi sottodomini (ad esempio, subdomain.examplepetstore.com).

      Per utilizzare una chiave su più di 250 domini, fai clic sul pulsante Disattiva verifica dominio. reCAPTCHA ignorerà l'elenco dei domini. Devi eseguire tu la verifica del dominio esaminando il tokenProperties.hostname campo nelle valutazioni che crei.

9. 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 Google Cloud console.

1. Se vuoi consentire alla chiave basata sul punteggio di funzionare con Accelerated Mobile Pages (AMP), attiva il pulsante Consenti il funzionamento di questa chiave con le pagine AMP.

2. 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 su Passaggio successivo (facoltativo).
   2. Nel passaggio Impostazioni aggiuntive, fai clic sul pulsante Stai creando questa chiave solo a scopo di test ?.
   3. Utilizza il cursore Imposta punteggio per specificare un punteggio compreso tra 0 e 1,0.
3. 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 della casella di controllo perché aumentano il fastidio per l'utente e non migliorano in modo significativo l'accuratezza.

1. Fai clic su Passaggio successivo (facoltativo).
2. Nel passaggio Impostazioni aggiuntive, attiva il pulsante Utilizzerai le verifiche? attiva/disattiva.
3. Seleziona l'opzione Sicurezza della verifica appropriata.

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

   Se vuoi garantire la migliore protezione antifrode, seleziona Difficile.

   Se selezioni Facile, è meno probabile che agli utenti venga richiesta la verifica visiva.

4. 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 Stai creando questa chiave solo a scopo di test?.
   2. Utilizza il cursore Imposta punteggio per specificare un punteggio compreso tra 0 e 1,0.
   3. Seleziona l'opzione Tipo di verifica appropriata.
      • Automatica mostra la verifica a volte.
      • Nessun CAPTCHA non mostra una verifica.
      • Verifica non risolvibile mostra le immagini, ma la verifica non viene superata.
   4. Fai clic su Crea chiave.

   La chiave appena creata è elencata nella pagina Chiavi reCAPTCHA.

Crea chiavi reCAPTCHA di verifica basate sulle norme

1. Fai clic su Passaggio successivo (facoltativo).
2. Nel passaggio Impostazioni aggiuntive, attiva il pulsante Utilizzerai le verifiche? attiva/disattiva.
3. Seleziona l'opzione Sicurezza della verifica appropriata.

   L'opzione di sicurezza della verifica definisce la complessità e la frequenza delle verifiche CAPTCHA mostrate all'utente.

   Se vuoi garantire la migliore protezione antifrode, seleziona Difficile.

   Se selezioni Facile, è meno probabile che agli utenti vengano richieste verifiche CAPTCHA meno complesse e meno frequenti.

4. 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 Stai creando questa chiave solo a scopo di test?.
   2. Utilizza il cursore Imposta punteggio per specificare un punteggio compreso tra 0 e 1,0.
5. Seleziona la soglia di punteggio per attivare le verifiche CAPTCHA, applicabile a tutte le azioni.
6. Fai clic su Crea chiave.

La chiave appena creata è elencata nella pagina Chiavi reCAPTCHA.

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:

• 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 della casella di controllo.
  • policy-based-challenge per le chiavi di verifica basate sulle norme.
  Nota: non è consigliabile utilizzare CHECKBOX perché aumenta il fastidio per l'utente e non migliora in modo significativo l'accuratezza. Per ulteriori informazioni, consulta le Domande frequenti.
• DISPLAY_NAME: nome della chiave. In genere, il nome di un sito.
• 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à l'elenco dei domini. Devi eseguire tu la verifica del dominio esaminando il tokenProperties.hostname campo nelle valutazioni che crei.

  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 tua chiave reCAPTCHA.

  Nota: 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 devi specificare i relativi sottodomini (ad esempio, subdomain.examplepetstore.com).
• DEFAULT_SCORE_THRESHOLD: per le chiavi di verifica basate sulle norme, definisce la soglia di verifica universale per la chiave quando non è definita una soglia di punteggio personalizzata.
• ACTION_SCORE_THRESHOLDS: per le chiavi di verifica basate sulle norme, specifica l'azione e il punteggio di soglia corrispondente compreso tra 0,0 e 1,0. Ad esempio, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'.
  Nota: nelle valutazioni vengono restituiti solo i punteggi finali calcolati dopo le verifiche. Il punteggio iniziale calcolato da reCAPTCHA viene confrontato con la soglia.

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 sull'API relative ai tipi di chiavi e ai tipi di integrazione, consulta la sezione Tipo di chiave e Tipo di integrazione.

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

• 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 della casella di controllo.
  • POLICY_BASED_CHALLENGE per le chiavi di verifica basate sulle norme.
  Nota: non è consigliabile utilizzare CHECKBOX perché aumenta il fastidio per l'utente e non migliora in modo significativo l'accuratezza. Per ulteriori informazioni, consulta le Domande frequenti.
• DISPLAY_NAME: nome della chiave. In genere, il nome di un sito.
• 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à l'elenco dei domini. Devi eseguire tu la verifica del dominio esaminando il tokenProperties.hostname campo nelle valutazioni che crei.

  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 tua chiave reCAPTCHA.

  Nota: 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 devi specificare i relativi sottodomini (ad esempio, subdomain.examplepetstore.com).
• DEFAULT_SCORE_THRESHOLD: per le chiavi di verifica basate sulle norme, definisce la soglia di verifica universale per la chiave quando non è definita una soglia di punteggio personalizzata.
• ACTION_SCORE_THRESHOLDS: per le chiavi di verifica basate sulle norme, specifica l'azione e il punteggio di soglia corrispondente compreso tra 0,0 e 1,0. Ad esempio, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'.
  Nota: nelle valutazioni vengono restituiti solo i punteggi finali calcolati dopo le verifiche. Il punteggio iniziale calcolato da reCAPTCHA viene confrontato con la soglia.
• DEFAULT_SCORE_THRESHOLD: per le chiavi di verifica basate sulle norme, definisce la soglia di verifica universale per la chiave quando non è definita una soglia di punteggio personalizzata. Questa funzionalità è in anteprima.
• ACTION_SCORE_THRESHOLDS: per le chiavi di verifica basate sulle norme, specifica l'azione e il punteggio di soglia corrispondente compreso tra 0,0 e 1,0. Ad esempio, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'. Questa funzionalità è in anteprima.
  Nota: nelle valutazioni vengono restituiti solo i punteggi finali calcolati dopo le verifiche. Il punteggio iniziale calcolato da reCAPTCHA viene confrontato con la soglia.

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": "INTEGRATION_TYPE"
  }
}

Per inviare la richiesta, scegli una di queste 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 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 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 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 Google Cloud progetto a un altro Google Cloud progetto.

(Facoltativo) Trova una chiave secret reCAPTCHA legacy

Se vuoi eseguire l'integrazione con un'applicazione di terze parti che non utilizza l'API reCAPTCHA Enterprise, ti serve la chiave secret legacy.

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

Se ti serve la chiave secret per una chiave reCAPTCHA Classic, allora esegui la migrazione della chiave a reCAPTCHA su Google Cloud e trova la chiave secret legacy.

Nota: non è consigliabile utilizzare una chiave secret legacy nel frontend perché sarà visibile agli utenti e gli autori di attacchi potranno abusare della tua applicazione.

Per trovare la chiave secret legacy:

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

   Vai a reCAPTCHA

2. Seleziona la scheda Chiavi.

3. Nella sezione Chiavi reCAPTCHA, trova la chiave reCAPTCHA che hai creato e fai clic sulla chiave.

   

4. Nella pagina Dettagli chiave, nella scheda Integrazione, fai clic su Utilizza chiave legacy. Si apre una finestra di dialogo con le istruzioni su come utilizzare la chiave secret legacy.

   

Passaggi successivi

• Installa le chiavi basate sul punteggio nelle tue pagine web.
• Installa le chiavi della casella di controllo nelle tue pagine web.
• Installa le chiavi di verifica basate sulle norme nelle tue pagine web.