Intégrer CaptchaAI à reCAPTCHA de Firebase Auth

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.

reCAPTCHA protège les parcours sensibles de Firebase Auth : inscription, connexion par téléphone, vérification App Check. Pour automatiser ces parcours dans vos propres environnements, il faut obtenir un token reCAPTCHA valide, puis l'injecter dans la même session que celle qui a déclenché le défi. C'est précisément ce que CaptchaAI industrialise : un token reCAPTCHA v2 récupéré via une API stable, prêt à passer votre validation Firebase. Ce guide montre comment câbler cette intégration pour qu'elle tienne en production : gestion propre des secrets, journalisation exploitable et tests rejouables.

Le parcours d'intégration en cinq étapes

1. Récupérez le sitekey reCAPTCHA de la page Firebase Auth concernée (inscription, connexion, App Check).
2. Soumettez la tâche à CaptchaAI depuis votre service et récupérez l'identifiant de tâche.
3. Interrogez le résultat à intervalle régulier jusqu'à obtenir un token reCAPTCHA v2 valide.
4. Injectez le token dans la même session que celle qui a déclenché le défi.
5. Transmettez la requête à Firebase Auth, vérifiez la réponse et tracez la latence de bout en bout.

Comment CaptchaAI s'insère dans votre flux Firebase Auth

Votre composant interne appelle CaptchaAI via HTTPS pour récupérer un token reCAPTCHA, puis le transmet à votre formulaire ou à votre route d'API qui déclenche Firebase Auth. Le token doit voyager avec le reste de la requête : mêmes cookies, même contexte navigateur, même client HTTP. Un token appliqué dans une session différente de celle qui a affiché le défi est la première cause de rejet après résolution.

Tracez chaque étape du parcours (obtention du sitekey, appel à CaptchaAI, injection du token, réponse de Firebase). Cette traçabilité facilite la détection des régressions lors des montées de version du SDK Firebase ou d'un changement de configuration reCAPTCHA côté console Google.

Stocker la clé API sans jamais la coder en dur

La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue. Le déploiement la monte en variable d'environnement au runtime ; le code source ne contient jamais la valeur en clair. Cette règle vaut autant pour vos machines de développement que pour vos workers hébergés, par exemple chez OVHcloud ou Scaleway.

Le code côté serveur

Voici un appel HTTP côté serveur, dans votre propre service, qui soumet un défi reCAPTCHA v2 à CaptchaAI et récupère l'identifiant de tâche :

import os
import requests

API_KEY = os.environ['CAPTCHAAI_KEY']

def submit_recaptcha_v2(sitekey: str, page_url: str) -> str:
    payload = {
        'clientKey': API_KEY,
        'task': {
            'type': 'NoCaptchaTaskProxyless',
            'websiteURL': page_url,
            'websiteKey': sitekey,
        },
    }
    resp = requests.post('https://api.captchaai.com/createTask', json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()['taskId']

La logique reste identique quel que soit le langage : soumettez la tâche, interrogez le résultat, puis injectez le token dans la requête Firebase. Vous la transposez sans peine vers Node.js, Go ou Java, tous compatibles HTTP.

Journalisation, observabilité et RGPD

Instrumentez chaque appel 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 vous permettent de distinguer un problème CaptchaAI d'un rejet côté Firebase.

Séparez les journaux par environnement (développement, préproduction, production) et corrélez chaque identifiant à votre traçage distribué, par exemple via OpenTelemetry. Vous pourrez rejouer un scénario complet à partir d'un identifiant unique, ce qui divise par deux le temps de diagnostic en cas d'incident. Côté conformité, minimisez les données personnelles écrites dans les logs : un token et un identifiant de tâche suffisent, inutile d'y déverser des identifiants d'utilisateurs réels, conformément à vos obligations RGPD.

Tests et intégration continue

Ajoutez des tests d'intégration sur vos endpoints critiques et publiez des métriques par environnement. Vos tableaux de bord internes doivent montrer la latence, le taux de réussite et la consommation. Un worker déployé dans une région européenne (par exemple eu-west-3 à Paris) rapproche la latence réseau de vos utilisateurs francophones et rend les mesures plus représentatives. Automatisez la validation dans votre pipeline pour que chaque déploiement rejoue le parcours reCAPTCHA de bout en bout.

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.
• Les durées d'appel et les codes retour sont tracés pour chaque exécution.
• Le token est injecté dans la même session que celle qui a déclenché le défi.
• Une stratégie de retry idempotent couvre les erreurs transitoires.
• Les tests sont rejouables et reproductibles depuis votre intégration continue.

Dépannage

Les incidents les plus fréquents se ramènent à quatre causes, toutes diagnosticables depuis vos journaux.

FAQ

Où stocker la clé API CaptchaAI dans une chaîne CI ?

Dans un secret CI ou un coffre (Vault, AWS Secrets Manager, Azure Key Vault), jamais dans le dépôt. Le pipeline la monte en variable d'environnement au moment de l'exécution, et vous la faites tourner régulièrement comme n'importe quel autre secret.

Pourquoi mon token reCAPTCHA est-il refusé après résolution ?

Presque toujours parce qu'il est injecté dans une session différente de celle qui a affiché le défi. Conservez le même contexte navigateur, le même client HTTP et le même stock de cookies entre l'affichage du CAPTCHA et l'appel à Firebase Auth.

Quelles données puis-je écrire dans les journaux sans risque RGPD ?

Limitez-vous aux métadonnées techniques : identifiant de tâche, durée, code retour HTTP. Évitez d'y consigner des identifiants d'utilisateurs réels ou des numéros de téléphone. Cette minimisation reste la ligne de conduite la plus sûre pour vos obligations de conformité.

Que faire face à une erreur transitoire de l'API ?

Mettez en place un retry avec backoff exponentiel borné (par exemple trois tentatives, doublement du délai, plafond à 30 secondes). Tracez chaque échec avec son identifiant de tâche ; si l'erreur persiste, vérifiez la configuration réseau (DNS, certificats) et les quotas associés à votre clé.

Guides connexes

• Le guide de démarrage rapide CaptchaAI
• Tester les CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégrer la résolution CAPTCHA dans votre CI
• Résoudre reCAPTCHA v2 via l'API

Fiabilisez vos workflows reCAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.