Cloudflare Turnstile : comment ça marche, ce qu'il voit de votre côté et comment l'installer — guide pas à pas

Introduction : ce que ce guide va vous apporter

Cloudflare Turnstile, c'est ce petit widget avec une roue qui tourne et l'inscription « Verifying » que vous voyez de plus en plus souvent à la place du captcha à images. Il est présent sur les formulaires d'inscription, dans les paniers des boutiques en ligne, sur les landing pages et dans les espaces clients des services. Le visiteur ordinaire le remarque à peine. Mais pour un marketeur, un affilié ou un développeur qui travaille via des proxys mobiles et ouvre des dizaines de sites par jour, il devient une énigme. Pourquoi sur un profil la vérification passe en une seconde, alors que sur un autre le widget réfléchit, demande de cocher une case ou renvoie un code d'erreur ?

Dans ce guide, on va décortiquer Cloudflare Turnstile sous deux angles. Côté propriétaire du site — vous installerez vous-même le widget sur une page, configurerez la vérification serveur et apprendrez à lire les statistiques. Côté visiteur — vous comprendrez quels signaux Turnstile collecte exactement, ce qu'il voit de votre navigateur, de votre réseau et de votre proxy, et pourquoi il prend telle ou telle décision. Ce savoir est aussi utile à ceux qui protègent leurs formulaires contre les bots qu'à ceux qui veulent que leurs profils de travail ressemblent à des utilisateurs ordinaires.

À qui s'adresse ce guide

• Aux propriétaires de business et marketeurs dont les demandes spam et les fausses inscriptions polluent les statistiques et grignotent le budget.
• Aux développeurs qui doivent intégrer Turnstile dans un formulaire rapidement et sans erreur, et vérifier correctement le token côté serveur.
• Aux affiliés et spécialistes du multi-compte qui travaillent via des proxys mobiles et veulent comprendre ce que Turnstile voit de leur connexion.

Ce qu'il faut savoir au préalable

Aucune compétence particulière n'est requise. Il suffit de comprendre ce qu'est une page HTML, de savoir ouvrir la console développeur dans un navigateur et d'avoir un minimum d'expérience avec un langage côté serveur — PHP, Node.js, Python. Si vous n'avez pas de partie serveur, vous parcourrez quand même la majorité du guide : le widget peut être installé et testé sur une page locale.

Combien de temps cela prend

Le parcours complet dure environ une heure et demie à deux heures. L'inscription et la création du widget prennent 10-15 minutes, l'intégration sur la page 20 minutes, la vérification serveur 30-40 minutes, les tests et le diagnostic encore 30 minutes. Les parties théoriques peuvent se lire dans n'importe quel ordre et se consulter au besoin.

Préparation : outils et accès

Avant de commencer, rassemblez tout le nécessaire. Cela vous évitera des pauses en cours de route.

Outils et accès nécessaires

• Un compte Cloudflare. Gratuit. Inscription par e-mail en quelques minutes. Pas besoin de transférer un domaine sur Cloudflare — Turnstile fonctionne sur n'importe quel site, où qu'il soit hébergé.
• Un site ou une page de test. N'importe quelle page HTML avec un formulaire fera l'affaire. Pour des expérimentations locales, un fichier sur votre ordinateur ouvert via un petit serveur local suffit.
• Un environnement serveur. N'importe quel hébergement avec PHP, ou Node.js ou Python sur votre machine. Nécessaire pour la seconde moitié du guide — la vérification du token.
• Un navigateur moderne. Chrome, Firefox, Edge ou Safari à jour, avec les outils de développement ouverts.
• Un proxy mobile capable de changer d'IP. Utile dans la partie diagnostic pour observer comment le widget réagit à différents réseaux et à la rotation d'adresses.

Configuration requise

Turnstile n'est pas exigeant. Le widget fonctionne dans tout navigateur qui prend en charge le JavaScript moderne et charge son code depuis le domaine challenges.cloudflare.com. Si ce domaine est bloqué dans votre réseau ou par une extension de navigateur, le widget ne se chargera pas — gardez-le en tête lors des tests. La vérification serveur nécessite la capacité d'émettre des requêtes HTTPS sortantes.

Ce qu'il faut préparer avant de commencer

1. Créez un fichier texte pour vos notes. Vous y noterez le site key, le nom du widget, la liste des hostnames et les résultats des tests.
2. Ouvrez la page avec le formulaire que vous souhaitez protéger et enregistrez-en une copie datée. C'est votre sauvegarde.
3. Si vous avez un gestionnaire de formulaire côté serveur, faites-en une copie aussi. Nous y ajouterons le code de vérification.
4. Vérifiez que votre serveur local ou de production sert la page en HTTPS ou via localhost. Turnstile fonctionne aussi en HTTP simple, mais sur un site en production il vous faudra de toute façon HTTPS.

⚠️ Attention : la clé secrète du widget ne doit jamais être stockée dans le HTML, dans le JavaScript de la page ou dans un dépôt public. Elle vit uniquement sur le serveur. Si vous l'avez publiée par erreur, régénérez immédiatement la clé dans le panneau Cloudflare — l'ancienne cessera de fonctionner.

Notions de base : comment fonctionne Cloudflare Turnstile

Pour que les étapes suivantes soient claires, passons en revue les termes clés en langage simple.

Termes clés

• Widget — le bloc que voit le visiteur. Techniquement, c'est un iframe chargé depuis le domaine Cloudflare et intégré à votre page.
• Site key — l'identifiant public du widget. Il s'insère dans le HTML et est visible de tous. Cloudflare s'en sert pour savoir quel widget afficher et pour quels domaines il est autorisé.
• Secret key — la clé privée. Votre serveur s'en sert pour confirmer que le token reçu est authentique. Ne quitte jamais le serveur.
• Token — la chaîne que le widget délivre après une vérification réussie. Elle est placée dans un champ caché du formulaire et part vers votre serveur avec les autres données.
• Siteverify — l'endpoint Cloudflare où le serveur envoie le token avec la clé secrète et reçoit une réponse : succès ou non.
• Mode du widget — le mode d'affichage : Managed (géré), Non-interactive (non interactif) ou Invisible. La différence est décrite plus bas.
• Hostname — le domaine sur lequel le widget est autorisé. Si le domaine n'est pas listé, le widget refusera de fonctionner avec une erreur.

Le principe en quatre phrases

1. La page charge le script Turnstile, et le widget lance discrètement une série de vérifications dans le navigateur.
2. Cloudflare collecte les résultats, les évalue avec les données réseau et décide : laisser passer tout de suite, afficher une case à cocher, ou refuser.
3. En cas de succès, le widget génère un token à usage unique et l'injecte dans le formulaire.
4. Votre serveur reçoit le formulaire, envoie le token à siteverify et ne traite la demande qu'en cas de réponse positive.

Ce que Turnstile vérifie — vue d'ensemble

L'essentiel à comprendre ici : Cloudflare Turnstile n'évalue pas « l'humanité » à travers des puzzles d'images. Il évalue la cohérence de l'environnement : à quel point le navigateur, le réseau et le comportement convergent vers une image crédible. Les grandes familles de signaux :

• L'environnement du navigateur. Le script exécute une série de petites tâches JavaScript et vérifie que l'environnement se comporte comme un vrai navigateur : la structure des objets window, le rendu graphique, la présence de traces d'automatisation, la cohérence entre le User-Agent déclaré et les capacités réelles du moteur.
• La preuve de travail. Le widget demande au navigateur d'effectuer un petit calcul. Pour un humain, c'est une fraction de seconde ; pour un bot qui ouvre des milliers de pages, c'est une charge notable.
• Les signaux réseau. La réputation de l'adresse IP et du système autonome d'où vient la requête, la cohérence des caractéristiques réseau avec le navigateur déclaré, l'historique des requêtes depuis cette adresse sur tout le réseau Cloudflare.
• Les jetons de confiance de l'appareil. Sur les appareils Apple et dans certains autres écosystèmes, Turnstile peut demander au système d'exploitation de confirmer qu'il s'agit d'un véritable appareil — et la vérification passe alors sans aucun calcul.
• Le comportement sur la page. Le moment d'apparition du widget, le moment de l'envoi du formulaire, le naturel des actions en mode géré.

Ce que Turnstile ne fait pas : il ne collecte pas de données pour du profilage publicitaire, ne suit pas l'utilisateur entre les sites via des cookies tiers et n'affiche jamais de puzzles d'images. C'est important tant du point de vue de la loi sur les données personnelles que de celui de la conversion — les visiteurs ne partent pas à cause d'un captcha agaçant.

Les trois modes du widget

• Managed — le mode par défaut. Le widget est visible, fait tourner l'indicateur, et en cas de doute affiche une case à cocher. Convient à la plupart des formulaires.
• Non-interactive — le widget est visible mais ne demande jamais d'action. Soit il passe tout seul, soit il renvoie une erreur. Idéal pour les pages où aucun clic superflu n'est possible.
• Invisible — le widget ne s'affiche pas du tout. La vérification se fait en arrière-plan. Pratique pour les boutons et formulaires dont vous ne voulez pas changer le design, mais exige une gestion soignée des erreurs.

Étape 1 : comprendre ce que Turnstile voit de votre côté

Objectif de l'étape : avant de configurer quoi que ce soit, vous devez comprendre quelles données sur votre environnement le widget reçoit. C'est la base du diagnostic des étapes suivantes et d'un travail conscient via des proxys mobiles.

Comment observer le widget de ses propres yeux

1. Ouvrez n'importe quel site équipé de Cloudflare Turnstile. Ces widgets se reconnaissent facilement au logo Cloudflare dans le coin inférieur droit du bloc et aux liens « Privacy » et « Terms ».
2. Appuyez sur F12 ou faites un clic droit — « Inspecter » pour ouvrir les outils de développement.
3. Allez dans l'onglet « Network » (Réseau) et rechargez la page.
4. Dans le filtre, tapez challenges.cloudflare.com. Vous verrez plusieurs requêtes : le chargement de api.js, le chargement de l'iframe du widget et une ou plusieurs requêtes POST — c'est l'envoi des résultats des vérifications.
5. Ouvrez l'onglet « Elements » (Éléments) et trouvez le bloc avec la classe cf-turnstile. À l'intérieur, après une vérification réussie, apparaîtra un champ input caché nommé cf-turnstile-response avec une longue chaîne en valeur. C'est le token.

Astuce : le contenu des requêtes POST est chiffré et obfusqué, le lire ne sert à rien. Observez autre chose : combien de requêtes sont parties, combien de temps a pris la vérification et si le statut du widget est passé à « Success ». C'est votre indicateur externe de confiance.

Ce que Turnstile voit de votre navigateur

Le widget exécute du JavaScript directement dans votre fenêtre, il a donc accès à tout ce qu'un script de la page peut voir : version du moteur, API installées, dimensions de l'écran, fuseau horaire, langues de l'interface, particularités du rendu graphique et des polices, comportement de fonctions souvent redéfinies dans les navigateurs automatisés. Il ne lit pas vos fichiers et ne fouille pas dans les autres onglets. Mais il remarque parfaitement quand un navigateur déclare une chose et en fait une autre. Par exemple, le User-Agent dit « Chrome sur Android », mais l'environnement n'a pas d'événements tactiles et possède des API absentes sur mobile.

Ce que Turnstile voit de votre réseau

C'est ici que ça devient intéressant pour ceux qui travaillent via des proxys mobiles. Toutes les requêtes du widget partent vers les serveurs Cloudflare, donc Cloudflare voit votre adresse IP externe, son système autonome (donc l'opérateur), le pays, ainsi que les caractéristiques bas niveau de la connexion — comment exactement votre client établit la connexion sécurisée. Ces caractéristiques diffèrent d'un navigateur à l'autre, et Cloudflare les compare au User-Agent déclaré.

Les opérateurs mobiles distribuent des adresses issues de grands pools partagés ; des centaines d'abonnés réels utilisent la même adresse en même temps. Ces adresses ont donc en elles-mêmes une réputation neutre ou bonne — les bloquer reviendrait à bloquer de vraies personnes. Mais la réputation n'est qu'un signal parmi d'autres. Si une adresse mobile envoie un navigateur dont l'empreinte réseau est celle d'un script desktop, avec un fuseau horaire d'un autre continent et des traces d'automatisation, le tableau cesse d'être cohérent et le widget passe en mode interactif ou refuse.

Ce que Turnstile voit de votre comportement

En mode géré, le widget prête attention à la vitesse à laquelle le formulaire est envoyé après le chargement, à l'interaction de l'utilisateur avec la page, au naturel du clic sur la case. En mode invisible et non interactif, la composante comportementale est minimale — la décision se prend sur l'environnement et le réseau.

✅ Vérification : à ce stade, vous devez savoir ouvrir l'onglet Network, filtrer les requêtes vers challenges.cloudflare.com, voir le champ caché cf-turnstile-response et expliquer avec vos mots les trois familles de signaux : navigateur, réseau, comportement. Si c'est acquis — passez à la création de votre widget.

Problèmes possibles

• Aucune requête vers challenges.cloudflare.com. Le domaine est probablement bloqué par une extension de navigateur ou un filtre d'entreprise. Désactivez les bloqueurs pendant les tests.
• Le widget reste bloqué en vérification indéfiniment. Vérifiez l'heure système de votre ordinateur : un écart important avec l'heure réelle casse la vérification.

Étape 2 : créer le widget dans le panneau Cloudflare

Objectif de l'étape : obtenir une paire de clés — site key et secret key — et bien configurer la liste des domaines et le mode de fonctionnement.

1. Ouvrez le panneau de contrôle Cloudflare et connectez-vous. Si vous n'avez pas de compte — cliquez sur « Sign up », entrez e-mail et mot de passe, confirmez l'e-mail.
2. Dans le menu de gauche, trouvez l'entrée Turnstile. Si vous avez plusieurs comptes, choisissez d'abord le bon sur la page d'accueil.
3. Cliquez sur le bouton bleu Add widget (Ajouter un widget).
4. Dans le champ Widget name, saisissez un nom clair, par exemple « Landing demandes — principal ». Le nom n'est visible que par vous, mais avec une dizaine de widgets il vous évitera bien des confusions.
5. Dans le bloc Hostname management, cliquez sur Add hostnames et saisissez les domaines sur lesquels le widget fonctionnera. Saisissez sans protocole et sans chemin : example.fr, et non https://example.fr/form. Les sous-domaines doivent être ajoutés séparément, ou indiquez le domaine racine — les sous-domaines seront alors aussi autorisés.
6. Pour les tests locaux, ajoutez localhost à la liste. C'est officiellement supporté et ça ne gêne pas la production.
7. Dans le bloc Widget Mode, choisissez le mode. Pour la première fois, prenez Managed — vous verrez ainsi tous les états du widget, y compris l'interactif.
8. Laissez l'option Pre-clearance désactivée pour l'instant. Elle n'est utile que si le site est proxifié via Cloudflare, on en parlera dans la section avancée.
9. Cliquez sur Create.
10. Sur l'écran suivant, vous verrez deux champs : Site Key et Secret Key. Copiez les deux dans votre fichier de notes. La clé secrète peut être revue plus tard dans les paramètres du widget, mais il est plus pratique de la sauvegarder tout de suite.

Astuce : créez d'emblée deux widgets — un pour le domaine de production, un second nommé « Test » avec localhost comme hostname. Vous expérimenterez ainsi les modes et réglages sans toucher aux statistiques du widget de travail.

À quoi ressemble un bon résultat

Dans la liste Turnstile apparaîtra une carte avec le nom du widget, son mode et la liste des hostnames. Le site key commence par « 0x » et fait environ 24 caractères, le secret key aussi par « 0x » mais plus long. Si la clé a une autre tête, vous avez probablement copié le mauvais champ.

✅ Vérification : dans votre fichier de notes figurent le site key, le secret key, le nom du widget, la liste des hostnames et le mode choisi. Dans le panneau Cloudflare, le widget apparaît dans la liste avec le statut actif.

Problèmes possibles

• Le bouton Create est inactif. Aucun hostname n'a été ajouté ou il a été saisi avec une erreur (protocole, slash, espace).
• L'entrée Turnstile est introuvable dans le menu. Vous êtes dans les paramètres d'un domaine précis. Remontez au niveau du compte — Turnstile vit là, pas dans une zone.

Étape 3 : intégrer le widget sur la page avec le formulaire

Objectif de l'étape : le widget s'affiche sur votre page, passe la vérification et injecte le token dans le formulaire.

Connecter le script

1. Ouvrez le fichier HTML de la page avec le formulaire dans un éditeur.
2. Dans le tag head ou avant la balise fermante body, ajoutez la ligne de chargement du script :

<script src='https://challenges.cloudflare.com/turnstile/v0/api.js' async defer></script>

Les attributs async et defer permettent à la page de ne pas attendre le chargement du script. Le widget apparaîtra un peu plus tard, mais l'utilisateur ne verra aucun délai dans le chargement du contenu.

Placer le conteneur du widget

1. Trouvez le formulaire à protéger. C'est en général un tag form avec des champs nom, e-mail, téléphone.
2. Juste avant le bouton d'envoi, insérez un bloc vide avec la classe cf-turnstile et votre site key :

<form action='/submit.php' method='POST'> <input type='text' name='name' placeholder='Votre nom'> <input type='email' name='email' placeholder='E-mail'> <div class='cf-turnstile' data-sitekey='VOTRE_SITE_KEY' data-theme='light'></div> <button type='submit'>Envoyer</button> </form>

1. Remplacez VOTRE_SITE_KEY par la clé de votre fichier de notes. La clé secrète ne doit pas être insérée ici.
2. Enregistrez le fichier et ouvrez la page dans un navigateur via localhost.

Ce que vous devez voir

Une à deux secondes après le chargement, un widget d'environ 300 sur 65 pixels apparaîtra à l'emplacement du bloc. Il affiche d'abord un indicateur de chargement et le texte « Verifying », puis une coche verte et « Success ». Si Cloudflare a décidé de revérifier l'environnement, une case à cocher avec le texte « Verify you are human » apparaîtra — cliquez dessus et le widget affichera le succès en un instant.

Ouvrez les outils de développement, onglet Elements, et dépliez le bloc cf-turnstile. Un champ input caché nommé cf-turnstile-response est apparu à l'intérieur. Sa valeur est un long token. C'est lui qui partira vers le serveur à l'envoi du formulaire.

Attributs utiles du conteneur

• data-theme — light, dark ou auto. Auto s'adapte au thème système de l'utilisateur.
• data-size — normal, compact ou flexible. Flexible étire le widget sur la largeur du conteneur — pratique pour le responsive.
• data-language — code de langue, par exemple fr. Par défaut, le widget prend la langue du navigateur.
• data-action — un libellé court, par exemple login ou checkout. Il reviendra dans la réponse siteverify et aidera à distinguer les formulaires dans les statistiques.
• data-callback — nom de la fonction JavaScript appelée en cas de succès. Elle recevra le token.
• data-error-callback — fonction qui recevra le code d'erreur en cas de problème.
• data-refresh-expired — que faire quand le token expire : auto le redemande tout seul, manual affiche un bouton de rafraîchissement, never ne fait rien.

Astuce : ajoutez tout de suite data-error-callback et affichez le code d'erreur dans la console. Les codes Turnstile sont parlants : la série 110xxx indique un problème de clé ou de domaine, 300xxx un échec d'exécution dans le navigateur, 600xxx une vérification non passée. Sans ça, vous devinerez pourquoi le widget reste muet.

Voie alternative : rendu explicite via JavaScript

Si vous travaillez dans un framework ou voulez contrôler le moment d'apparition du widget, remplacez le rendu implicite par un rendu explicite. Ajoutez le paramètre render=explicit à l'adresse du script et appelez turnstile.render avec les paramètres voulus :

turnstile.render('#my-widget', { sitekey: 'VOTRE_SITE_KEY', theme: 'auto', action: 'signup', callback: function(token) { console.log('Token reçu', token.length); } });

Cette méthode permet de redessiner le widget après une erreur avec turnstile.reset et de récupérer le token courant avec turnstile.getResponse.

✅ Vérification : le widget s'affiche sur la page, montre « Success », le champ cf-turnstile-response avec le token est présent dans le DOM, aucune erreur en console. Essayez de recharger la page trois ou quatre fois — un nouveau token doit apparaître à chaque fois.

Problèmes possibles

• Le widget affiche l'erreur 110200. Le domaine depuis lequel la page est ouverte n'est pas dans les hostnames du widget. Vérifiez que vous ouvrez bien via localhost, et non via 127.0.0.1 ou file:// — ce sont des hostnames différents.
• Le widget n'apparaît pas, la console est vide. Le script ne s'est pas chargé. Vérifiez l'adresse du script pour une faute de frappe et l'absence de bloqueurs.
• Le widget casse la mise en page. Utilisez data-size='flexible' ou enveloppez le bloc dans un conteneur de la largeur voulue.

Étape 4 : configurer la vérification serveur du token

Objectif de l'étape : le serveur rejette tout envoi de formulaire sans token valide. C'est l'étape la plus importante — sans elle, le widget reste purement décoratif, car un bot peut envoyer une requête POST directement, en contournant la page.

Comment fonctionne la requête vers siteverify

Votre serveur envoie une requête POST à l'adresse https://challenges.cloudflare.com/turnstile/v0/siteverify avec les champs :

• secret — votre clé secrète ;
• response — le token du champ cf-turnstile-response ;
• remoteip — l'IP du visiteur, facultatif mais utile ;
• idempotency_key — identifiant unique facultatif de la requête, on en parlera dans la partie avancée.

En réponse arrive un JSON. Les champs clés :

{ "success": true, "challenge_ts": "2026-03-14T10:22:31.000Z", "hostname": "example.fr", "error-codes": [], "action": "signup", "cdata": "" }

Le token vit 300 secondes et est à usage unique. Une revérification du même token renverra l'erreur timeout-or-duplicate.

Exemple en PHP

1. Ouvrez le fichier de traitement du formulaire, par exemple submit.php.
2. Au tout début, avant tout traitement des données du formulaire, ajoutez le bloc de vérification :

<?php $token = $_POST['cf-turnstile-response'] ?? ''; if ($token === '') { http_response_code(400); exit('Vérification échouée : aucun token'); } $data = [ 'secret' => getenv('TURNSTILE_SECRET'), 'response' => $token, 'remoteip' => $_SERVER['REMOTE_ADDR'] ]; $ch = curl_init('https://challenges.cloudflare.com/turnstile/v0/siteverify'); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 10); $raw = curl_exec($ch); curl_close($ch); $result = json_decode($raw, true); if (empty($result['success'])) { http_response_code(403); exit('Vérification échouée : ' . implode(',', $result['error-codes'] ?? ['no-response'])); } 






À propos de l'auteur










Roman Melnikov
Technical Writer and System Administrator







Expérience professionnelle :
Technical writer and DevOps engineer with 9 years of experience. Created over 50 detailed guides on system configuration and administration. His instructions helped thousands of professionals successfully solve technical tasks. Popular author on Habr and YouTube.







Formation :

Bauman Moscow State Technical University. Information Systems and Technologies








Expertise :

Technical Documentation
DevOps
System Administration
Linux
Docker and Kubernetes
CI/CD
Infrastructure Automation
Cloud Technologies
System Monitoring
Bash and Python Scripting












Partagez cet article :