Périmètre sûr : ce guide ne concerne que vos propres applications — environnements de développement, de recette, de préproduction ou de production — ou des systèmes pour lesquels vous détenez une autorisation écrite. Il n'aborde ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'anti-bot.
reCAPTCHA se forge un avis sur chaque visiteur bien avant le premier clic sur la case. Dès le chargement de la page, il attribue à la session un score de risque en croisant des dizaines de signaux : cohérence du navigateur, rythme des interactions, historique rattaché au profil. Sur vos propres applications, comprendre cette logique n'a rien à voir avec l'évasion : c'est ce qui vous permet de régler correctement vos seuils, de réserver le défi le plus sévère aux sessions réellement douteuses et d'arrêter de pénaliser vos utilisateurs légitimes.
Les signaux que reCAPTCHA prend en compte
Google ne publie pas sa formule, mais les signaux observés se regroupent en trois familles.
La cohérence du navigateur. reCAPTCHA vérifie qu'un navigateur se présente de façon homogène : un profil qui annonce Chrome sur Windows doit exposer les objets, extensions et propriétés de rendu attendus. Une incohérence entre ce que le navigateur déclare et ce qu'il expose réellement fait baisser le score.
Le comportement pendant la session. C'est la couche la plus déterminante. reCAPTCHA observe le déplacement du curseur, le rythme de frappe, l'ordre des interactions et le délai entre le chargement et le premier geste. Une saisie humaine varie naturellement ; une saisie parfaitement régulière ou instantanée attire l'attention.
L'historique du profil. Via le cookie _GRECAPTCHA et l'analyse côté serveur de Google, une session hérite de la réputation du profil qui l'a générée. Un profil neuf, sans historique et sans cookies stables, part d'un score plus prudent.
Calibrer les seuils de score dans votre application
reCAPTCHA v3 renvoie un score continu entre 0,0 (probablement automatisé) et 1,0 (probablement humain). L'erreur classique consiste à traiter ce score comme un booléen. Définissez plutôt deux seuils : un seuil bas au-dessus duquel la requête passe sans friction, et un seuil haut en dessous duquel vous déclenchez une revue manuelle interne ou un second facteur, plutôt qu'un rejet sec.
Avant de figer ces valeurs, tracez la distribution réelle des scores observés sur votre trafic légitime pendant quelques jours. Vous découvrirez presque toujours que le seuil « par défaut » de 0,5 est mal adapté à votre audience. Si vos tests de recette doivent produire un token reCAPTCHA v2 valide de bout en bout, appuyez-vous sur la résolution de reCAPTCHA v2 via l'API plutôt que de piloter un navigateur à la main.
Vérifier le token côté serveur
Un score ne vaut que s'il est validé au bon endroit. La vérification du token se fait toujours côté serveur, jamais dans le navigateur : c'est le seul moyen d'empêcher qu'un client falsifie le résultat.
Exemple Python pour valider le token auprès de votre propre backend :
import requests
def verify_token_with_backend(token: str, your_backend_url: str) -> bool:
"""Vérifier le token CAPTCHA avec votre propre backend."""
response = requests.post(
your_backend_url + '/api/captcha/verify',
json={'token': token},
timeout=15,
)
response.raise_for_status()
return response.json().get('valid', False)
Le token a une durée de vie courte (de l'ordre de deux minutes) : vérifiez-le immédiatement après réception et ne le mettez jamais en cache pour un usage ultérieur.
Journaliser sans sur-collecter
Instrumentez vos appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP et identifiant de tâche. Corrélez chaque appel à votre traçage distribué (par exemple OpenTelemetry) et séparez les journaux par environnement, afin de rejouer un scénario complet à partir d'un seul identifiant.
Côté conformité : le score et les signaux comportementaux touchent à des données personnelles. Appliquez le principe de minimisation du RGPD — ne conservez que ce qui sert au débogage, fixez une durée de rétention et documentez la finalité, plutôt que de tout journaliser « au cas où ».
Un scénario de recette avant mise en production
Prenons une équipe qui déploie ses workers de test dans la région eu-west-3 (Paris). Avant chaque mise en production, elle rejoue le parcours d'inscription protégé par reCAPTCHA sur une préproduction dédiée, en périmètre autorisé. Un plan CaptchaAI BASIC ($15/mois, 5 threads) suffit pour ce volume de recette, et la facturation par thread évite toute mauvaise surprise pendant les campagnes de tests. Voir la démarche complète dans la QA CAPTCHA en environnements autorisés.
Liste de contrôle avant déploiement
- Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
- La clé secrète reCAPTCHA et la clé CaptchaAI vivent dans un secret CI ou un coffre, jamais dans le code source.
- Le token est vérifié côté serveur, immédiatement après réception.
- Les seuils de score reposent sur la distribution réelle de votre trafic, pas sur la valeur par défaut.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Une stratégie de retry idempotent couvre les erreurs transitoires.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
| Trop d'utilisateurs légitimes bloqués | Seuil de score trop haut | Abaissez le seuil après avoir tracé la distribution réelle des scores |
| Score systématiquement bas en préproduction | Profils de test sans historique ni cookies stables | Testez avec des profils persistants et isolez la vérification côté serveur |
| Token refusé à la vérification | Token expiré ou clé secrète erronée | Vérifiez le token dès sa réception et contrôlez la clé côté serveur |
| Scores incohérents entre environnements | Clés de site distinctes ou domaines non déclarés | Alignez une clé par environnement et déclarez chaque domaine dans la console |
FAQ
Quelle différence entre le score reCAPTCHA v2 et v3 ?
reCAPTCHA v2 renvoie une réussite binaire après une case à cocher ou un défi visuel, tandis que reCAPTCHA v3 renvoie un score continu entre 0,0 et 1,0 sans interruption de l'utilisateur. En v3, c'est à votre application de décider ce qu'elle fait de ce score : laisser passer, demander une confirmation ou déclencher une revue.
Un score bas signifie-t-il forcément un robot ?
Non. Un score bas indique une session que reCAPTCHA juge à risque, ce qui inclut des utilisateurs réels derrière un VPN d'entreprise, un profil neuf ou une connexion partagée. Traitez le score comme un signal parmi d'autres et privilégiez une friction progressive plutôt qu'un rejet immédiat.
Où stocker la clé secrète reCAPTCHA ?
Dans un secret d'intégration continue ou un coffre (par exemple un gestionnaire de secrets), jamais dans le dépôt ni dans le code côté navigateur. La clé secrète ne doit servir qu'à la vérification serveur ; seule la clé de site, publique par nature, apparaît dans la page.
Puis-je tester reCAPTCHA dans ma CI sans pénaliser mon score ?
Oui, à condition de rester sur votre propre environnement de recette et vos propres clés. Isolez la préproduction, utilisez des clés de test dédiées et intégrez la validation à votre pipeline comme décrit dans l'intégration CAPTCHA en CI.
Guides connexes
- Le démarrage rapide CaptchaAI
- Tester l'endpoint API sur vos formulaires
- Résoudre Cloudflare Turnstile via l'API
Passez d'un score subi à un score maîtrisé sur vos propres applications, avec une méthode reproductible. — Obtenez votre clé CaptchaAI.
