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 couvre ni l'automatisation de sites tiers, ni l'évasion de protections anti-bot que vous ne contrôlez pas.
Dès que vous activez le Recaptcha flow dans Keycloak, un reCAPTCHA v2 apparaît sur les pages de connexion et d'inscription. Pour qu'un test de bout en bout ou un job planifié franchisse cette étape sans humain, il faut résoudre le token côté serveur, puis l'injecter dans la même session que celle qui a affiché le défi. C'est le rôle de l'API CaptchaAI.
L'objectif n'est pas de faire marcher le flux une fois dans un notebook, mais de le rendre stable pour tourner sans surveillance en intégration continue. Latence prévisible, échecs propres, code relu en cinq minutes : voilà la barre.
Comment Keycloak déclenche reCAPTCHA v2
Keycloak câble reCAPTCHA comme un exécuteur (« authenticator ») dans le flux d'authentification. Le formulaire rend un widget reCAPTCHA v2 à partir de votre sitekey Google, et le serveur valide le champ g-recaptcha-response avant la soumission. Votre automatisation doit donc produire ce token comme le ferait un utilisateur qui coche la case, puis le poster avec les autres champs. Deux paramètres suffisent au solveur : le sitekey exposé dans le HTML et l'URL exacte du formulaire ; le reste (cookies, jeton d'état) reste géré par votre client HTTP.
Architecture cible
Un composant interne de votre pile appelle CaptchaAI en HTTPS pour obtenir un token, puis le réinjecte dans le formulaire ou la route d'API que Keycloak protège. Isolez cet appel derrière une petite fonction dédiée : vous tracez chaque étape et détectez immédiatement une régression lors d'une montée de version de Keycloak ou d'un changement de thème.
Le déroulé d'intégration, étape par étape
L'ordre compte. Une intégration qui tient en production suit toujours la même séquence.
- Capturez les paramètres attendus. Récupérez uniquement ce dont le solveur a besoin : le sitekey et l'URL de la page. Stocker davantage crée de fausses pistes de débogage.
- Envoyez la tâche à l'API CaptchaAI et récupérez son identifiant. Traitez toute réponse inattendue comme une erreur et journalisez-la.
- Interrogez le résultat en polling jusqu'à obtention du token, avec un plafond de temps par tâche.
- Injectez le token dans la même session : même contexte de navigateur, même client HTTP, même cookie jar. Une session dépareillée est la première cause de rejet après résolution.
- Mesurez la latence, les retentatives et l'acceptation en aval. Réussite du solveur et réussite du workflow sont deux métriques distinctes.
Gestion des secrets
La clé API CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI, jamais dans le code source. Le déploiement la monte en variable d'environnement au runtime. Pour un hébergement européen, un secret CI côté OVHcloud ou Scaleway remplit le même rôle : la clé ne doit jamais transiter par un dépôt Git ni par un log en clair.
Exemple de code
Appel HTTP côté serveur, dans votre propre service, pour soumettre un reCAPTCHA v2 et récupérer 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 : soumettre, interroger, injecter. Le motif se transpose de Python vers Node.js, Go ou Java.
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA pour des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Ces signaux alimentent vos tableaux de bord et vos alertes.
Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué, par exemple via OpenTelemetry : vous rejouez un scénario complet à partir d'un identifiant unique. Comme un flux Keycloak manipule des identités, minimisez les données personnelles dans les logs (e-mails, identifiants) : bonne pratique de traçage et obligation RGPD à la fois.
Un exemple concret
Prenez une équipe QA d'un éditeur SaaS français dont le SSO repose sur Keycloak. Chaque nuit, un test de non-régression crée un utilisateur, se connecte et vérifie qu'un ticket support remonte. Le Recaptcha flow bloquait ce scénario tant qu'un humain devait cocher la case ; en résolvant le token via l'API CaptchaAI en préproduction, le job tourne désormais sans surveillance. La facturation par thread avec résolutions illimitées aide : le plan BASIC ($15/mois, 5 threads) couvre la plupart des pipelines d'intégration continue.
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é API CaptchaAI est stockée dans un coffre ou un secret CI, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Le token est appliqué dans la même session que celle qui a affiché le défi.
- Un retry idempotent, avec backoff exponentiel borné, gère les erreurs transitoires.
- Les tests sont rejouables et reproductibles depuis votre intégration continue.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la comme secret CI. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez avant de relancer et ajoutez une alerte de solde. |
ERROR_CAPTCHA_UNSOLVABLE |
Défi non résolu de façon fiable. | Relancez une fois ; si cela persiste, capturez le HTML et ouvrez un ticket. |
FAQ
Pourquoi le token reCAPTCHA est-il refusé après une résolution réussie ?
Neuf fois sur dix, le token a été appliqué dans une session différente de celle qui a affiché le défi. Gardez la résolution et la soumission dans le même contexte de navigateur, avec le même cookie jar. Vérifiez aussi que l'URL envoyée au solveur correspond exactement à celle du formulaire Keycloak.
Comment tester le flux reCAPTCHA de Keycloak sans exposer de vraies données ?
Activez le Recaptcha flow dans un realm de préproduction dédié, avec des utilisateurs et un sitekey de test. Vous validez l'intégration sans toucher au realm de production ni manipuler d'identités réelles, ce qui limite votre exposition RGPD.
Quel plan CaptchaAI convient à un pipeline d'intégration continue ?
Pour la plupart des jobs planifiés, le plan BASIC ($15/mois, 5 threads) suffit : chaque thread traite des résolutions illimitées dans le mois. Passez au plan STANDARD ($30/mois, 15 threads) si vous saturez vos threads avec des tests en parallèle.
Que faire face à une erreur transitoire de l'API ?
Mettez en place un retry avec backoff exponentiel borné : trois tentatives, doublement du délai à chaque essai, 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 le solde de votre clé.
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
Donnez à vos workflows CAPTCHA une base méthodique et reproductible. – Obtenez votre clé CaptchaAI.
