Valider les jetons de réponse de l'utilisateur avec l'ancienne fonctionnalité SiteVerify

Cette page explique comment valider la réponse d'un utilisateur à un test reCAPTCHA à partir du backend de votre application à l'aide de l'ancien point de terminaison de l'API SiteVerify (https://www.google.com/recaptcha/api/siteverify). N'utilisez ce point de terminaison que si vous gérez une ancienne intégration ou un ancien plug-in tiers qui ne peut pas utiliser CreateAssessment.

Avant de commencer

Pour appeler le point de terminaison SiteVerify, vous avez besoin de l'ancienne clé secrète de votre clé. Pour trouver la clé secrète dans la console Google Cloud , consultez Récupérer la clé secrète dans la console Google Cloud . Conservez votre clé secrète en sécurité sur votre serveur backend et ne l'exposez jamais dans le code côté client.

Récupérer le jeton de réponse de l'utilisateur

Les anciennes intégrations Web chargent l'API JavaScript non Enterprise (https://www.google.com/recaptcha/api.js), qui fournit des méthodes sur l'objet grecaptcha au lieu de grecaptcha.enterprise. Vous pouvez récupérer le jeton de réponse de l'utilisateur sur votre interface utilisateur de l'une des manières suivantes :

  • À partir du paramètre POST g-recaptcha-response lorsque l'utilisateur envoie un formulaire sur votre site.
  • En appelant grecaptcha.getResponse(opt_widget_id) une fois que l'utilisateur a terminé un test reCAPTCHA v2. Cette méthode renvoie le jeton de réponse sous forme de chaîne ou une chaîne vide si le défi n'est pas relevé. Le paramètre facultatif opt_widget_id spécifie l'ID du widget renvoyé par grecaptcha.render(). S'il est omis, il est défini par défaut sur le premier widget créé.
  • En tant qu'argument de chaîne transmis à votre fonction de rappel lorsque l'utilisateur termine un défi, si vous spécifiez le nom de la fonction de rappel dans l'attribut data-callback de l'élément HTML g-recaptcha ou dans le paramètre callback de la méthode grecaptcha.render(container, parameters).
  • À partir de la valeur résolue de Promise renvoyée par grecaptcha.execute(site_key, {action: action_name}) pour les clés basées sur un score (v3).

Les anciennes méthodes grecaptcha (render, getResponse, execute, ready et reset) et les attributs de balise g-recaptcha utilisent les mêmes paramètres que les équivalents grecaptcha.enterprise. Pour en savoir plus sur les paramètres, consultez la documentation de référence de l'API JavaScript pour reCAPTCHA.

Pour migrer vers l'API JavaScript reCAPTCHA mise à jour, consultez Migrer l'API JavaScript reCAPTCHA.

Restrictions liées aux jetons

Chaque jeton de réponse de l'utilisateur à un test reCAPTCHA est valide pendant deux minutes et ne peut être validé qu'une seule fois pour éviter les attaques par relecture. Validez le jeton de réponse avec reCAPTCHA dans les deux minutes suivant sa réception. Si vous avez besoin d'un nouveau jeton, relancez la validation reCAPTCHA.

Requête API

Envoyez une requête avec le point de terminaison et la méthode suivants :

  • URL : https://www.google.com/recaptcha/api/siteverify (ou https://www.recaptcha.net/recaptcha/api/siteverify si www.google.com n'est pas accessible ; consultez Utiliser reCAPTCHA dans le monde entier)
  • Méthode : POST

Incluez les paramètres POST suivants dans la requête :

Paramètre POST Description
secret Obligatoire. Clé secrète partagée entre votre site et reCAPTCHA.
response Obligatoire. Jeton de réponse de l'utilisateur fourni par l'intégration côté client de reCAPTCHA sur votre site.
remoteip Facultatif. Adresse IP de l'utilisateur.

Réponse de l'API

Le point de terminaison SiteVerify renvoie un objet JSON.

Pour les intégrations Web (clés basées sur le score v3, à cocher v2 ou invisibles v2), la réponse se présente comme suit :

{
  "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
}

Informations de référence sur les codes d'erreur

Le tableau suivant décrit les codes d'erreur qui peuvent s'afficher dans le tableau error-codes :

Code d'erreur Description
missing-input-secret Le paramètre secret est manquant.
invalid-input-secret Le paramètre secret n'est pas valide ou son format est incorrect.
missing-input-response Le paramètre response est manquant.
invalid-input-response Le paramètre response n'est pas valide ou son format est incorrect.
bad-request La requête n'est pas valide ou son format est incorrect.
timeout-or-duplicate La réponse n'est plus valide, car elle a expiré ou a déjà été utilisée.

Étapes suivantes