Esegui la migrazione da reCAPTCHA classico

Questo documento spiega come eseguire la migrazione di una chiave di sito attiva da reCAPTCHA Classic a reCAPTCHA in un Google Cloud progetto. Puoi eseguire la migrazione della chiave di sito utilizzando la Console di amministrazione di reCAPTCHA (consigliata) o utilizzando la Google Cloud console. Il completamento della procedura di migrazione richiede 5-10 minuti e non richiede modifiche al codice.

Se gestisci le chiavi nella Console di amministrazione di reCAPTCHA, stai utilizzando reCAPTCHA Classic. Le funzionalità più recenti di reCAPTCHA sono disponibili solo per le chiavi di sito gestite all'interno di un Google Cloud progetto. Per ulteriori informazioni sulle funzionalità disponibili, consulta Confronta i livelli di reCAPTCHA.

Dopo aver completato la procedura di migrazione, si verificano le seguenti modifiche:

  • Le chiavi di sito sono disponibili in un Google Cloud progetto senza modifiche.
  • L'integrazione reCAPTCHA esistente continua a funzionare senza richiedere modifiche al codice. Puoi conservare la stessa strumentazione della pagina web e le stesse chiamate di backend. Tuttavia, per accedere a funzionalità come Account Defender o Password Defense, devi modificare la strumentazione della pagina web e le chiamate di backend. Per ulteriori informazioni, consulta Utilizzare le funzionalità di reCAPTCHA dopo la migrazione.
  • Ti verrà addebitato un costo quando superi la quota mensile senza costi di reCAPTCHA, ovvero 10.000 test al mese. Per ulteriori informazioni, consulta Dati di fatturazione.

Eseguire la migrazione utilizzando la Console di amministrazione di reCAPTCHA

  1. Vai alla Console di amministrazione di reCAPTCHA.

    Vai alla Console di amministrazione di reCAPTCHA

  2. Seleziona il progetto in cui vuoi eseguire la migrazione delle chiavi.

  3. Seleziona le chiavi di cui eseguire la migrazione.

  4. Fai clic su Invia.

La Google Cloud console si apre con il tuo progetto e le chiavi di cui hai eseguito la migrazione.

Eseguire la migrazione utilizzando la Google Cloud console

Prima di iniziare

  1. Nella Google Cloud console, nella pagina di selezione del progetto, seleziona o crea un Google Cloud progetto.

    Ruoli richiesti per selezionare o creare un progetto

    • Selezionare un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto su cui ti è stato concesso un ruolo.
    • Creare un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.

    Vai al selettore di progetti

  2. Verifica che la fatturazione sia abilitata per il tuo Google Cloud progetto.

    Per la migrazione, reCAPTCHA richiede che la fatturazione sia collegata e abilitata nel progetto per la migrazione. Puoi abilitare la fatturazione utilizzando una carta di credito o un esistente Google Cloud ID di fatturazione del progetto. Se hai bisogno di assistenza per la fatturazione, contatta l'assistenza per la fatturazione Cloud.

  3. Se vuoi eseguire gcloud CLI al di fuori della Google Cloud console, installa e inizializza gcloud CLI. Per le istruzioni, consulta

    Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il seguente comando: 

    gcloud init

    Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Abilitare l'API reCAPTCHA Enterprise

Tutti i livelli di reCAPTCHA (Essentials, Premium ed Enterprise) vengono eseguiti sull'API reCAPTCHA Enterprise.

Console

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

    Vai all'API reCAPTCHA Enterprise

  2. Verifica che il nome del tuo progetto venga visualizzato nel selettore di progetti nella parte superiore della pagina.

    Se non vedi il nome del tuo progetto, fai clic sul selettore di progetti e seleziona il progetto.

  3. Fai clic su Attiva.

gcloud

  1. Nella Google Cloud console, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della Google Cloud console viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già inclusa e installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Per impostare il tuo Google Cloud progetto nella sessione gcloud, esegui il gcloud config set project comando. Sostituisci PROJECT_ID con l'ID del tuo Google Cloud progetto. 
           gcloud config set project PROJECT_ID
  3. Per abilitare l'API reCAPTCHA Enterprise, esegui il gcloud services enable comando: 
             gcloud services enable recaptchaenterprise.googleapis.com
  4. Per verificare che l'API reCAPTCHA Enterprise sia abilitata, esegui il gcloud services list comando: 
             gcloud services list --enabled

    Verifica che l'API reCAPTCHA Enterprise sia presente nell'elenco delle API abilitate.

Eseguire la migrazione a reCAPTCHA

Per eseguire la migrazione da reCAPTCHA Classic a reCAPTCHA, scegli una chiave di sito attiva dalla Console di amministrazione di reCAPTCHA ed esegui la migrazione della chiave di sito. Puoi eseguire la migrazione di una o più chiavi di sito attive. Tuttavia, puoi eseguire la migrazione di una sola chiave di sito alla volta.

Per eseguire la procedura di migrazione, devi disporre di un account utente reCAPTCHA che soddisfi i seguenti requisiti:

  • Nella Console di amministrazione di reCAPTCHA, l'account utente è elencato come proprietario della chiave di sito di cui vuoi eseguire la migrazione.
  • L'account utente ha uno dei seguenti ruoli IAM per il Google Cloud progetto per cui è abilitata l'API reCAPTCHA Enterprise: abilitata:
    • Proprietario progetto (roles/owner)
    • Project Editor (roles/editor)
    • Amministratore reCAPTCHA (roles/recaptchaenterprise.admin)
    Se il tuo account utente non ha uno di questi ruoli, chiedi all'amministratore di concederlo o segui le istruzioni riportate in Concedere, modificare e revocare l'accesso.

  1. Esegui la migrazione della chiave di sito utilizzando la Google Cloud console, Google Cloud CLI o l'API reCAPTCHA Enterprise.

    La migrazione della chiave di sito non influisce sulla chiave o sugli endpoint API; aggiunge la chiave alla licenza Enterprise.

    Google Cloud Console

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

    3. Nella sezione Chiavi classiche , individua la chiave di cui vuoi eseguire la migrazione e fai clic su Esegui l'upgrade della chiave.

    4. Per completare la migrazione della chiave selezionata, fai clic su Conferma.

    Gcloud CLI

    1. Per configurare l'autenticazione, esegui il seguente comando gcloud:

      gcloud auth login

      Accedi con l'account utente reCAPTCHA proprietario della chiave di sito scelta e con uno dei seguenti ruoli: Project Owner, Project Editor o Amministratore reCAPTCHA Enterprise.

    2. Scegli e copia una chiave di sito attiva che hai utilizzato per integrare reCAPTCHA nelle tue pagine web:

      1. Vai alla Console di amministrazione di reCAPTCHA e fai clic su .

      2. Scegli una chiave di sito. Per la migrazione sono supportate le seguenti chiavi di sito reCAPTCHA: reCAPTCHA v2 Checkbox, reCAPTCHA v2 Invisible e reCAPTCHA v3.

      3. Per copiare la chiave di sito, fai clic su Copia chiave di sito.

    3. Esegui la migrazione della chiave di sito.

      Utilizza il gcloud recaptcha keys migrate comando come mostrato nel seguente esempio:

       gcloud recaptcha keys migrate SITE_KEY --project PROJECT-ID

      Fornisci i seguenti valori:

      • SITE_KEY: la chiave di sito attiva che hai copiato dalla Console di amministrazione di reCAPTCHA.
      • PROJECT-ID: l'ID del Google Cloud progetto per cui è abilitata l'API reCAPTCHA Enterprise.

    API REST

    1. Scegli e copia una chiave di sito attiva che hai utilizzato per integrare reCAPTCHA nelle tue pagine web:

      1. Vai alla Console di amministrazione di reCAPTCHA e fai clic su .

      2. Scegli una chiave di sito. Per la migrazione sono supportate le seguenti chiavi di sito reCAPTCHA: reCAPTCHA v2 Checkbox, reCAPTCHA v2 Invisible e reCAPTCHA v3.

      3. Per copiare la chiave di sito, fai clic su Copia chiave di sito.

    2. Esegui la migrazione della chiave di sito.

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

      • PROJECT_ID: l'ID del Google Cloud progetto per cui è abilitata l'API reCAPTCHA.
      • SITE_KEY: la chiave di sito attiva che hai copiato dalla Console di amministrazione di reCAPTCHA.

      Metodo HTTP e URL: 

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

      Per inviare la richiesta, scegli una di queste opzioni:

      curl

      Esegui questo comando: 

      curl -X POST \
           -H "Authorization: Bearer $(gcloud auth print-access-token)" \
           -H "Content-Type: application/json; charset=utf-8" \
           -d "" \
           "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate"

      PowerShell

      Esegui questo comando: 

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

      Invoke-WebRequest `
          -Method POST `
          -Headers $headers `
          -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/SITE_KEY:migrate" | Select-Object -Expand Content

      Dovresti ricevere una risposta JSON simile alla seguente:

      {
  "name": "projects/PROJECT-ID/keys/6Ldqgs0UAAAAAIn4k7YxEB-LwEh5S9-Gv6IIWB8m",
  "displayName": "My site key",
  "webSettings": {
    "allowAllDomains": false,
    "allowedDomains": [
      recaptcha.net
    ],
    "allowAmpTraffic": false,
    "integrationType": "SCORE",
    "challengeSecurityPreference": "CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED"
  }
}

  2. Per verificare che la chiave di sito sia stata migrata:

    Google Cloud Console

    Vai alla pagina reCAPTCHA e trova la chiave di sito migrata nella sezione Chiavi reCAPTCHA.

    Vai a reCAPTCHA

    Gcloud CLI

    Esegui il comando gcloud recaptcha keys list e trova la chiave di sito migrata nell'elenco delle chiavi.

Dopo la migrazione a reCAPTCHA, puoi continuare a utilizzare il metodo siteverify per valutare il token di risposta reCAPTCHA di un utente. Per informazioni sulla risposta, consulta Risposta del siteverify method.

Dopo la migrazione di una chiave di sito a reCAPTCHA, l'utilizzo inizia a essere registrato per la visualizzazione nella Google Cloud console entro un'ora, inclusi i dashboard relativi all'utilizzo e al punteggio. In genere, l'utilizzo precedente alla migrazione non viene visualizzato nella console Google Cloud .

Puoi revocare il ruolo IAM Amministratore reCAPTCHA Enterprise (roles/recaptchaenterprise.admin) dal tuo account utente reCAPTCHA. Puoi chiedere all'amministratore di revocare l'accesso, o seguire le istruzioni riportate in Concedere, modificare e revocare l'accesso.

Passaggi successivi