Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'anti-bot.
Un Credentials Provider d'Auth.js (NextAuth) exécute sa fonction authorize() entièrement côté serveur. C'est précisément l'endroit où vous validez un token CAPTCHA avant d'accorder une session, et donc l'endroit où CaptchaAI s'intègre. Lorsque votre page de connexion est protégée par un défi Turnstile ou reCAPTCHA, un test automatisé doit obtenir un token valide, puis le transmettre au serveur exactement comme le ferait un navigateur réel.
L'objectif n'est pas de faire fonctionner ce flux une seule fois dans un notebook. Il s'agit de le rendre suffisamment stable pour tourner sans surveillance : en intégration continue, dans une tâche planifiée ou derrière une file d'attente interne. Les sections ci-dessous décrivent l'architecture, l'obtention du token, la gestion des secrets et l'observabilité qui tiennent la charge en production.
Où le CAPTCHA s'insère dans un Credentials Provider
Dans une configuration NextAuth classique, le formulaire envoie l'e-mail, le mot de passe et le champ cf-turnstile-response à la route d'authentification. Votre authorize() reçoit ces valeurs dans credentials, vérifie le token auprès du fournisseur, puis renvoie l'objet utilisateur ou null. Tant que la vérification échoue, aucune session n'est créée.
Pour un scénario de test autorisé sur votre propre application, votre harnais doit reproduire ce contrat côté client : il obtient un token via CaptchaAI, l'ajoute au payload de connexion, puis observe la réponse de NextAuth. Tracer chaque étape — soumission de la tâche, réception du token, appel de connexion — facilite la détection des régressions lors des montées de version, aussi bien du côté d'Auth.js que du fournisseur anti-bot.
Obtenir le token côté serveur avec CaptchaAI
Côté serveur, le composant interne enchaîne trois étapes :
- Créer la tâche via un appel HTTPS à CaptchaAI.
- Interroger le résultat jusqu'à récupérer le token.
- Injecter le token dans le formulaire ou la route d'API.
CaptchaAI expose une API unique pour reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3 et les CAPTCHA image/OCR : vous changez le type de tâche sans réécrire cette boucle d'obtention.
La facturation repose sur le nombre de threads concurrents, avec des résolutions illimitées par thread : l'offre BASIC ($15/mois, 5 threads) suffit largement à couvrir une suite de tests de connexion. Un thread correspond à un CAPTCHA en cours ; dès qu'une résolution se termine, le thread reprend la tâche suivante. Pour un pipeline de QA, cela signifie un coût prévisible même quand le volume de tests augmente.
Exemple : créer une tâche Turnstile pour votre page de connexion
L'appel HTTP ci-dessous s'exécute côté serveur, dans votre propre service. Il crée une tâche Turnstile à partir du siteKey de votre page et renvoie l'identifiant de tâche que vous interrogerez ensuite pour récupérer le token.
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Une fois le token obtenu, appliquez-le dans la même session que celle qui a déclenché le défi : même contexte de navigateur, même client HTTP, même gestion des cookies. Un token appliqué dans une session différente est la cause la plus fréquente de rejet après résolution.
Stocker la clé API en toute sécurité
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue, jamais dans le code source ni dans un fichier .env versionné. Le déploiement monte la clé en variable d'environnement au runtime, ce que reflète le process.env.CAPTCHAAI_KEY de l'exemple.
Côté conformité, appliquez le principe de minimisation : ne journalisez jamais le mot de passe testé ni le token en clair, et vérifiez vos obligations RGPD dès qu'un environnement manipule des identifiants réels. Un jeu de comptes de test dédié à la préproduction évite d'exposer des données personnelles dans vos traces.
Observabilité et journalisation
Instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces signaux alimentent vos tableaux de bord de QA et vos alertes, et distinguent la réussite de la résolution de la réussite de la connexion — deux métriques différentes qu'il faut suivre séparément.
Séparez les journaux par environnement (développement, préproduction, production) et corrélez les identifiants à votre traçage distribué, par exemple via OpenTelemetry. Vous pourrez ainsi rejouer un scénario complet en partant d'un identifiant unique. En cas d'incident, ces journaux divisent par deux le temps de diagnostic.
Liste de contrôle avant la mise en production
- Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un secret CI ou un coffre, jamais dans le code source.
- La vérification du token a bien lieu dans
authorize(), côté serveur, avant la création de session. - Le token est appliqué dans la même session que celle qui a déclenché le défi.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Une stratégie de retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
- Les tests sont rejouables et reproductibles depuis votre intégration continue.
Questions fréquentes
Faut-il valider le token CAPTCHA dans authorize() ou côté client ?
Dans authorize(), côté serveur. Une vérification uniquement côté client peut être contournée en modifiant le payload de la requête. Le Credentials Provider de NextAuth est l'endroit naturel pour vérifier le token auprès du fournisseur avant de renvoyer l'objet utilisateur, et donc avant d'ouvrir une session.
Comment automatiser le test d'une connexion NextAuth protégée par CAPTCHA ?
Sur votre propre application ou en préproduction, faites obtenir le token par CaptchaAI, ajoutez-le au payload de connexion aux côtés des identifiants de test, puis vérifiez la réponse de NextAuth. Isolez l'environnement, tracez chaque appel et exécutez le scénario depuis votre intégration continue pour qu'il reste reproductible.
Que faire si le token Turnstile est refusé après résolution ?
Vérifiez d'abord que le token est appliqué dans la même session que le défi et qu'il n'a pas expiré : un token Turnstile a une durée de vie courte, résolvez-le au plus près de l'envoi. Contrôlez ensuite que le websiteKey correspond bien au sitekey affiché sur la page. En cas d'erreur transitoire de l'API, appliquez un retry avec backoff exponentiel borné (par exemple trois tentatives, plafond à 30 secondes) et tracez chaque échec avec son identifiant de tâche.
Ce guide couvre-t-il l'automatisation de sites tiers ?
Non. Tous les exemples portent sur vos propres applications ou sur des environnements de test pour lesquels vous disposez d'une autorisation écrite. Si votre projet implique une source externe, validez d'abord les conditions d'utilisation et la base juridique avant d'engager toute automatisation.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA des CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution de CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Améliorez la qualité de vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
