Verificare i token di risposta dell'utente con SiteVerify legacy

Questa pagina spiega come verificare la risposta di un utente a una richiesta di verifica reCAPTCHA dal backend della tua applicazione utilizzando l'endpoint API SiteVerify legacy (https://www.google.com/recaptcha/api/siteverify). Utilizza questo endpoint solo se gestisci un'integrazione legacy o un plug-in di terze parti che non può utilizzare CreateAssessment.

Prima di iniziare

Per chiamare l'endpoint SiteVerify, devi disporre della chiave segreta legacy della chiave. Per trovare la chiave segreta nella console Google Cloud , vedi Recuperare la chiave segreta nella console Google Cloud . Conserva la chiave segreta in modo sicuro sul server di backend e non esporla mai nel codice lato client.

Recuperare il token di risposta dell'utente

Le integrazioni web legacy caricano l'API JavaScript non enterprise (https://www.google.com/recaptcha/api.js), che fornisce metodi sull'oggetto grecaptcha anziché su grecaptcha.enterprise. Puoi recuperare il token di risposta dell'utente nel frontend in uno dei seguenti modi:

  • Dal parametro POST g-recaptcha-response quando l'utente invia un modulo sul tuo sito.
  • Chiamando grecaptcha.getResponse(opt_widget_id) dopo che l'utente completa una verifica reCAPTCHA v2. Questo metodo restituisce il token di risposta come stringa o una stringa vuota se la verifica non viene completata. Il parametro facoltativo opt_widget_id specifica l'ID widget restituito da grecaptcha.render(); se omesso, viene impostato come predefinito il primo widget creato.
  • Come argomento stringa passato alla funzione di callback quando l'utente completa una sfida, se specifichi il nome della funzione di callback nell'attributo data-callback dell'elemento HTML g-recaptcha o nel parametro callback del metodo grecaptcha.render(container, parameters).
  • Dal valore risolto di Promise restituito da grecaptcha.execute(site_key, {action: action_name}) per le chiavi basate sul punteggio (v3).

I metodi legacy grecaptcha (render, getResponse, execute, ready e reset) e gli attributi del tag g-recaptcha utilizzano gli stessi parametri degli equivalenti grecaptcha.enterprise. Per i dettagli sui parametri, consulta il riferimento dell'API JavaScript per reCAPTCHA.

Per eseguire la migrazione all'API JavaScript reCAPTCHA aggiornata, consulta Eseguire la migrazione dell'API JavaScript reCAPTCHA.

Limitazioni relative ai token

Ogni token di risposta dell'utente reCAPTCHA è valido per due minuti e puoi verificare ogni token solo una volta per evitare attacchi di tipo replay. Verifica il token di risposta con reCAPTCHA entro due minuti dalla ricezione. Se hai bisogno di un nuovo token, esegui di nuovo la verifica reCAPTCHA.

Richiesta API

Invia una richiesta con l'endpoint e il metodo seguenti:

  • URL: https://www.google.com/recaptcha/api/siteverify (o https://www.recaptcha.net/recaptcha/api/siteverify se www.google.com non è accessibile; vedi Utilizzare reCAPTCHA a livello globale)
  • Metodo: POST

Includi i seguenti parametri POST nella richiesta:

Parametro POST Descrizione
secret Obbligatorio. La chiave segreta condivisa tra il tuo sito e reCAPTCHA.
response Obbligatorio. Il token di risposta dell'utente fornito dall'integrazione reCAPTCHA lato client sul tuo sito.
remoteip Facoltativo. L'indirizzo IP dell'utente.

Risposta dell'API

L'endpoint SiteVerify restituisce un oggetto JSON.

Per le integrazioni web (chiavi basate sul punteggio v3, con casella di controllo v2 o invisibili v2), la risposta ha il seguente formato:

{
  "success": true|false,      // whether this request was a valid reCAPTCHA token for your site
  "score": number,            // the score for this request (0.0 - 1.0) for score-based (v3) keys
  "action": string,           // the action name for this request (important to verify)
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

Messaggio del codice di errore

La seguente tabella descrive i codici di errore che possono essere visualizzati nell'array error-codes:

Codice di errore Descrizione
missing-input-secret Il parametro secret non è presente.
invalid-input-secret Il parametro secret non è valido o è in un formato non corretto.
missing-input-response Il parametro response non è presente.
invalid-input-response Il parametro response non è valido o è in un formato non corretto.
bad-request La richiesta non è valida o ha un formato non corretto.
timeout-or-duplicate La risposta non è più valida perché è scaduta o è già stata utilizzata.

Passaggi successivi