Comment fonctionne reCAPTCHA Enterprise Account Defender

Périmètre sûr : ce guide vise uniquement vos propres applications et environnements (QA, préproduction, production) ou des systèmes pour lesquels vous détenez une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement d'une protection tierce.

reCAPTCHA Enterprise Account Defender est la fonction de Google qui suit le comportement au niveau du compte et attribue à chacun un score de risque pour repérer les prises de contrôle de comptes. Elle s'appuie sur l'évaluation reCAPTCHA Enterprise déjà présente sur vos pages et l'enrichit d'un identifiant de compte. Cet article détaille qui produit quoi, ce que vous contrôlez côté serveur, et comment garder l'intégration stable en QA comme en production.

Le rôle d'Account Defender dans la chaîne reCAPTCHA Enterprise

Posez d'abord le schéma à trois acteurs : le navigateur qui affiche le widget et déclenche le défi, le service reCAPTCHA Enterprise qui produit le token et l'évaluation, et votre backend qui vérifie ce token et décide de la suite. Account Defender agit au troisième temps : avec un identifiant de compte (haché) joint à la requête, Google renvoie, en plus du score, des verdicts propres au compte — activité suspecte, identifiants compromis, appareil inhabituel. Ces signaux ne décident rien à votre place ; votre code les interprète.

Ce que vous contrôlez côté serveur

Trois leviers vous appartiennent :

• La configuration du widget : clé de site, action déclarée, variante (v2 ou v3 Enterprise).
• La vérification serveur : appelez l'API d'évaluation avec le token reçu, jamais depuis le navigateur, et lisez le score comme un indicateur, pas un verdict binaire.
• La réponse appliquée : au-dessus d'un seuil vous passez, en zone grise vous ajoutez une étape (MFA), en dessous vous bloquez.
• Le calibrage des seuils : sur vos propres données, jamais des valeurs d'un tutoriel.

Envoyer une tâche à l'API

Dans une suite de tests que vous contrôlez, automatisez la partie « obtenir un token valide » pour vérifier que votre backend réagit correctement au score. L'exemple ci-dessous soumet une tâche reCAPTCHA à CaptchaAI et récupère l'identifiant de tâche ; l'interrogation suit.

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']

Gardez la clé API hors du code source : un secret CI ou un coffre, jamais en clair. Appliquez le token dans la même session que celle qui a déclenché le défi, sinon la vérification serveur le rejette.

Données de compte et RGPD

Account Defender part d'un identifiant de compte, et c'est là qu'un réflexe RGPD s'impose pour les équipes en France, en Belgique ou en Suisse. Transmettez un identifiant haché plutôt qu'une adresse e-mail en clair, ne conservez pas les scores au-delà de ce qu'exige la détection de fraude, et documentez cette base légale. Des workers hébergés sur OVHcloud ou Scaleway en Europe réduisent en prime la latence.

Observabilité et journalisation

Séparez les journaux par environnement et corrélez chaque identifiant à votre traçage distribué (OpenTelemetry) pour rejouer un scénario complet. Remontez au moins quatre signaux vers vos tableaux de bord de QA :

• la durée totale d'obtention du token ;
• le code retour HTTP ;
• l'identifiant de tâche ;
• la taille de la file d'attente interne.

Liste de contrôle

• Le périmètre reste limité à vos applications ou à des sources autorisées.
• La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le dépôt.
• Chaque exécution trace sa durée d'appel, son code retour et son identifiant de tâche.
• Les erreurs transitoires passent par un retry idempotent avec backoff exponentiel borné.
• Les seuils de score sont calibrés sur vos données et revus à chaque changement de trafic.

FAQ

Account Defender remplace-t-il le score reCAPTCHA classique ?

Non. Il s'ajoute à l'évaluation reCAPTCHA Enterprise : vous recevez toujours un score, enrichi de verdicts liés au compte. Votre backend décide.

Faut-il vérifier le token côté serveur ?

Oui, systématiquement. L'évaluation se fait par un appel serveur à serveur avec votre clé secrète ; ne lisez jamais le score depuis le navigateur, où il serait falsifiable. Un token n'est valable qu'une fois.

CaptchaAI prend-il en charge reCAPTCHA Enterprise ?

Oui. reCAPTCHA v2 Enterprise et v3 Enterprise sont pris en charge (GA), via la même méthode userrecaptcha : même boucle d'envoi et d'interrogation.

Que faire en cas d'erreur transitoire de l'API ?

Appliquez un retry avec backoff exponentiel borné — trois tentatives, délai doublé, plafond à 30 s. Tracez chaque échec avec son identifiant de tâche ; si l'erreur persiste, vérifiez DNS, certificats et quotas.

Guides connexes

• le démarrage rapide CaptchaAI
• la QA CAPTCHA en environnements autorisés
• tester l'endpoint API sur vos formulaires
• intégrer la résolution CAPTCHA en CI
• résoudre reCAPTCHA v2 via l'API

Passez à une intégration reCAPTCHA Enterprise mesurable et reproductible. – Obtenez votre clé CaptchaAI.