Guide du développeur
Le widget hCaptcha peut protéger vos applications contre les robots, le spam et d'autres formes d'abus automatisés. L'installation de hCaptcha est rapide et facile. Cela nécessite soit l'ajout d'un simple code HTML et côté serveur, soit l'utilisation de l'un des nombreux outils prenant en charge nativement hCaptcha.
Pour rendre l'intégration encore plus rapide, des wrappers et des plugins sont disponibles pour de nombreux frameworks : Angular, Node, Express, ReactJS, VueJS, WordPress et plus encore.
Une liste complète des intégrations hCaptcha connues est également disponible.
Si vous utilisez déjà le reCAPTCHA de Google, vous pouvez utiliser votre code existant avec quelques légères modifications. Les méthodes hCaptcha sont compatibles API avec les méthodes reCAPTCHA, par exemple render() et onload() . Les attributs de données personnalisés tels que theme , size et tab-index sont également pris en charge de la même manière par hCaptcha.
Principes de base
Vous intégrez le widget hCaptcha sur votre site. Par exemple, sur un formulaire de connexion. L'utilisateur répond à un hCaptcha. Ils reçoivent un mot de passe de notre serveur qui est intégré à votre formulaire. Lorsque l'utilisateur clique sur Soumettre, le mot de passe est envoyé à votre serveur sous le formulaire. Votre serveur vérifie ensuite ce mot de passe avec l'API du serveur hCaptcha. hCaptcha dit qu'il est valide. Votre serveur sait désormais que l'utilisateur n'est pas un robot et lui permet de se connecter. Assez simple !
Flux de requête
Paramètres de politique de sécurité du contenu
Les en-têtes de stratégie de sécurité du contenu (CSP) constituent une couche de sécurité supplémentaire qui permet d'atténuer certains types d'attaques, notamment les attaques de type Cross Site Scripting (XSS), le détournement de clics et les attaques par injection de données.
Si vous utilisez des en-têtes CSP, veuillez ajouter les éléments suivants à votre configuration :
script-srcdoit inclurehttps://hcaptcha.com, https://*.hcaptcha.comframe-srcdoit inclurehttps://hcaptcha.com, https://*.hcaptcha.comstyle-srcdoit inclurehttps://hcaptcha.com, https://*.hcaptcha.comconnect-srcdoit inclurehttps://hcaptcha.com, https://*.hcaptcha.com
Veuillez ne pas coder en dur des sous-domaines spécifiques, comme newassets.hcaptcha.com , dans votre CSP : les sous-domaines d'actifs utilisés peuvent varier dans le temps ou selon la région.
Si vous êtes un client entreprise et que vous souhaitez activer une vérification supplémentaire, vous pouvez éventuellement choisir la stratégie CSP suivante :
unsafe-evaletunsafe-inlinedoivent inclurehttps://hcaptcha.com, https://*.hcaptcha.com
Ajoutez le widget hCaptcha à votre page Web
hCaptcha nécessite deux petits morceaux de code côté client pour afficher un widget captcha sur une page HTML. Tout d'abord, vous devez inclure la ressource javascript hCaptcha quelque part dans votre page HTML. Le <script> doit être chargé via HTTPS et peut être placé n'importe où sur la page. À l'intérieur de la balise <head> ou immédiatement après le conteneur .h-captcha, c'est tous les deux très bien.
<script src="https://js.hcaptcha.com/1/api.js" async defer></script>`
Deuxièmement, vous devez ajouter un conteneur DOM vide dans lequel le widget hCaptcha sera inséré automatiquement. Le conteneur est généralement un (mais peut être n'importe quel élément) et doit avoir la classeh-captcha et un attributdata-sitekey défini sur la clé publique de votre site.
En règle générale, vous souhaiterez inclure le conteneur .h-captcha vide dans un formulaire HTML. Lorsqu'un captcha est résolu avec succès, un jeton caché sera automatiquement ajouté à votre formulaire que vous pourrez ensuite POST sur votre serveur pour vérification. Vous pouvez le récupérer côté serveur avec le paramètre POST h-captcha-response .
Voici un exemple complet où hCaptcha est utilisé pour protéger un formulaire d'inscription contre les abus automatisés. Lorsque le formulaire est soumis, le jetonh-captcha-response sera inclus avec les données POST de l'e-mail et du mot de passe une fois le captcha résolu.
<html>
<head>
<title>hCaptcha Demo</title>
<script src="https://js.hcaptcha.com/1/api.js" async defer></script>
</head>
<body>
<form action="" method="POST">
<input type="text" name="email" placeholder="Email" />
<input type="password" name="password" placeholder="Password" />
<div class="h-captcha" data-sitekey="your_site_key"></div>
<br />
<input type="submit" value="Submit" />
</form>
</body>
</html>
Vérifiez le côté serveur de réponse utilisateur
En ajoutant le code côté client, vous avez pu générer un widget hCaptcha qui identifiait si les utilisateurs étaient de vraies personnes ou des robots automatisés. Lorsque le captcha réussit, le script hCaptcha insère un jeton unique dans les données de votre formulaire.
Pour vérifier que le jeton est bien réel et valide, vous devez maintenant le vérifier au niveau du point de terminaison de l'API :
https://api.hcaptcha.com/siteverify
Le point de terminaison attend une requête POST avec deux paramètres : le secret de votre compte et le jetonh-captcha-response envoyé depuis votre HTML frontend vers votre backend pour vérification. Vous pouvez éventuellement inclure l'adresse IP de l'utilisateur comme contrôle de sécurité supplémentaire. N'envoyez pas de données JSON : le point de terminaison attend un formulaire POST codé en URL standard.
Un test simple ressemblera à ceci :
curl https://api.hcaptcha.com/siteverify \
-X POST \
-d "response=CLIENT-RESPONSE&secret=YOUR-SECRET"
Notez que le point de terminaison attend le type de contenu application/x-www-form-urlencoded . Vous pouvez voir exactement ce qui est envoyé en utilisant
curl -vv
dans l'exemple ci-dessus.
N'utilisez pas de requête GET pour appeler /siteverify. Utilisez une requête POST et transmettez les paramètres dans le corps du formulaire, pas l'URL.
Bien que le point de terminaison puisse répondre correctement à une requête GET ou à une requête POST utilisant des paramètres d'URL, cela n'est pas garanti. Si les paramètres que vous envoyez à GET sont trop longs, la requête échouera et vous ne pourrez pas valider les codes d'accès. L'utilisation d'une requête POST garantit que vous n'aurez pas ce problème.
Veuillez noter que vous devez appeler /siteverify avec le secret de votre compte afin de valider que les codes d'accès que les utilisateurs vous envoient sont réels et non expirés. Vous ne pourrez pas non plus valider les codes d'accès d'une clé de site dans un compte si vous utilisez le secret d'un autre compte.
| Paramètre POST | Descriptif |
|---|---|
| secret | Requis. Clé secrète de votre compte. |
| response | Requis. Le jeton de vérification que vous avez reçu lorsque l'utilisateur a complété le captcha sur votre site. |
| remoteip | Facultatif. L'adresse IP de l'utilisateur. |
| sitekey | Facultatif. La clé de site que vous attendez de voir. |
Les jetons ne peuvent être utilisés qu’une seule fois et doivent être vérifiés dans un court laps de temps après leur émission. Pour récupérer le token sur votre serveur, utilisez le paramètre POSTh-captcha-response soumis par votre formulaire.
Nous vous recommandons de transmettre le paramètre sitekey, car cela empêchera les jetons émis sur un sitekey d'être échangés ailleurs. En fonction de vos paramètres de difficulté, cela peut n'avoir aucun impact sur la sécurité, mais si vous définissez un niveau de difficulté plus élevé et n'appliquez pas les correspondances de clé de site, un adversaire pourrait potentiellement résoudre un défi plus facile sur une autre clé de site, puis l'échanger contre un défi plus difficile.
# PSEUDO CODE
SECRET_KEY = "your_secret_key" # replace with your secret key
VERIFY_URL = "https://api.hcaptcha.com/siteverify"
# Retrieve token from post data with key 'h-captcha-response'.
token = request.POST_DATA['h-captcha-response']
# Build payload with secret key and token.
data = { 'secret': SECRET_KEY, 'response': token }
# Make POST request with data payload to hCaptcha API endpoint.
response = http.post(url=VERIFY_URL, data=data)
# Parse JSON from response. Check for success or error codes.
response_json = JSON.parse(response.content)
success = response_json['success']
Votre requête POST recevra une réponse JSON. Vous devez vérifier le champsuccess et n'exécuter votre logique métier normale que sisuccess esttrue . Sinon, vérifiez le champerror-codes pour un code d'erreur lisible par l'homme et renvoyez un message d'erreur approprié à l'utilisateur final.
Voici à quoi ressemble une réponse JSON de hCaptcha :
{
"success": true|false, // is the passcode valid, and does it meet security criteria you specified, eg sitekey?
"challenge_ts": timestamp, // timestamp of the challenge (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
"hostname": string, // the hostname of the site where the challenge was solved
"credit": true|false, // optional: deprecated field
"error-codes": [...] // optional: any error codes
"score": float, // ENTERPRISE feature: a score denoting malicious activity.
"score_reason": [...] // ENTERPRISE feature: reason(s) for score.
}
(Voir hCaptcha.com Enterprise pour plus de détails sur les fonctionnalités de hCaptcha Enterprise telles que les scores des robots, les modes « No-CAPTCHA » passifs et presque passifs, et plus encore.)
Veuillez noter que le champ de crédit n'est pas toujours inclus et qu'il sera obsolète au troisième trimestre 2023.
Veuillez également noter que le champ du nom d'hôte est dérivé du navigateur de l'utilisateur et ne doit pas être utilisé pour une authentification de quelque nature que ce soit ; il est principalement utile comme mesure statistique. De plus, dans le cas où votre site connaît un trafic de défi inhabituellement élevé, le champ du nom d'hôte peut être renvoyé comme « non fourni » plutôt que comme valeur habituelle ; tous les autres champs renverront leurs valeurs normales.
Tableau des codes d'erreur de Siteverify
Voici les codes d'erreur qui peuvent être renvoyés par l'API hCaptcha :
| Code d'erreur | Descriptif |
|---|---|
| missing-input-secret | Votre clé secrète est manquante. |
| invalid-input-secret | Votre clé secrète est invalide ou mal formée. |
| missing-input-response | Le paramètre de réponse (jeton de vérification) est manquant. |
| invalid-input-response | Le paramètre de réponse (jeton de vérification) est invalide ou mal formé. |
| bad-request | La demande est invalide ou mal formée. |
| invalid-or-already-seen-response | Le paramètre de réponse a déjà été vérifié ou présente un autre problème. |
| not-using-dummy-passcode | Vous avez utilisé une clé de site de test mais vous n'avez pas utilisé son secret correspondant. |
| sitekey-secret-mismatch | La clé de site n'est pas enregistrée avec le secret fourni. |
Rotation de votre secret de vérification de site
Votre secret de vérification de site est uniquement destiné à l'authentification sécurisée de machine à machine ; cela ne devrait jamais être exposé publiquement.
Si le secret de vérification de votre site a été involontairement exposé, vous pouvez recevoir un avertissement par e-mail de notre part.
Vous pouvez également la faire pivoter vous-même à tout moment en visitant le tableau de bord, en choisissant l'icône de votre profil et l'option de menu Paramètres, puis en cliquant sur Obtenir une nouvelle clé secrète. Assurez-vous de copier cette valeur ! Nous ne le conservons pas, vous ne pourrez donc plus le revoir.
Vous recevrez un e-mail de confirmation quelques secondes après la rotation.
Remarque : Les utilisateurs Enterprise disposent d'options supplémentaires pour gérer les secrets par rapport aux utilisateurs Free et Pro.
Par exemple, les comptes Enterprise peuvent créer plusieurs secrets Sitekey avec une expiration facultative et attribuer des secrets à une ou plusieurs clés de site pour permettre la segmentation des secrets par environnement, des clés uniques par équipe, etc. Veuillez consulter la documentation Enterprise pour plus de détails.
Développement Local
Si vous développez sur votre machine locale, il y a quelques points à garder à l'esprit.
Les navigateurs modernes ont des règles CORS et CORB strictes, donc ouvrir un file://URI qui charge hCaptcha ne fonctionnera pas. Le chargement de hCaptcha depuis http://localhost/ rencontrera le même problème sur certains navigateurs. L'API hCaptcha interdit également localhost et 127.0.0.1 comme noms d'hôte fournis.
Le moyen le plus simple de contourner ces problèmes consiste à ajouter une entrée d’hôtes. Par exemple:
127.0.0.1 test.mydomain.com
Placez-le dans /etc/hosts sous Linux, /private/etc/hosts sous Mac OS X ouC:\Windows\System32\Drivers\etc\hosts sous Windows.
Vous pourrez ensuite accéder à votre serveur local via http://test.mydomain.com, et tout fonctionnera comme prévu.
Types de scripts dactylographiés
Comment installer
Vous pouvez installer nos types dactylographiés @hcaptcha/types pour la variable globalehcaptcha en utilisant votre gestionnaire de packages préféré :
yarn add -D @hcaptcha/types
ou
npm install -D @hcaptcha/types
Comment utiliser
Localement
import '@hcaptcha/types';
//`hcaptcha` now is defined on the global object
hcaptcha.execute();
ou
///<reference types="@hcaptcha/types"/>
// `hcaptcha` now is defined on the global object
hcaptcha.execute();
Dans le monde
Ajoutez une importation ou une référence à votre.d.ts :
import "@hcaptcha/types";
// or
/// <reference types="@hcaptcha/types"/>
Ou ajoutez "node_modules/@hcaptcha" au typeRoots dans tsconfig.json
{
"compilerOptions": {
// ...
"typeRoots": [
"node_modules/@hcaptcha"
]
// ...
},
// ...
}
Tests d'intégration : clés de test
Si vous avez l'intention d'exécuter des tests d'intégration automatisés qui accèdent à un serveur en direct, l'approche la plus simple consiste à utiliser les clés de site hCaptcha de test suivantes qui génèrent toujours un mot de passe sans poser de question. Ces mots de passe ne peuvent être vérifiés qu’à l’aide du secret de test.
:::prudence Les clés de test n'offrent aucune protection anti-bot, veuillez donc vérifier que vous les utilisez uniquement dans votre environnement de test ! :::
Ensemble de clés de test : compte éditeur ou compte Pro
| Paramètre de test | Valeur |
|---|---|
| sitekey | 10000000-ffff-ffff-ffff-000000000001 |
| secret | 0x0000000000000000000000000000000000000000 |
| response | 10000000-aaaa-bbbb-cccc-000000000001 |
Cette paire de clés ne contestera jamais et produira toujours le même jeton de réponse, qui renverra success: true lorsqu'il sera transmis au point de terminaison avec ce secret. La réponse siteverify contiendra les champs trouvés dans les comptes Publisher et Pro.
Si vous êtes un client Enterprise, veuillez plutôt utiliser les paires de clés de test ci-dessous pour vous assurer que vous utilisez bien les champs score et d'autres champs Enterprise siteverify .
Ensemble de clés de test : compte d'entreprise (utilisateur final sécurisé)
| Paramètre de test | Valeur |
|---|---|
| Clé du site | 20000000-ffff-ffff-ffff-000000000002 |
| Clé secrète | 0x0000000000000000000000000000000000000000 |
| Jeton de réponse | 20000000-aaaa-bbbb-cccc-000000000002 |
Ensemble de clés de test : compte d'entreprise (bot détecté)
| Paramètre de test | Valeur |
|---|---|
| Clé du site | 30000000-ffff-ffff-ffff-000000000003 |
| Clé secrète | 0x0000000000000000000000000000000000000000 |
| Jeton de réponse | 30000000-aaaa-bbbb-cccc-000000000003 |
Pour les utilisateurs de hCaptcha Enterprise, les deux paires de clés ci-dessus vous permettront de vérifier le comportement de votre application dans les scénarios de score les plus courants. Veuillez contacter vos ingénieurs de support d'intégration pour obtenir des conseils si vous avez des questions supplémentaires.
Quelle est la prochaine étape ?
Bravo! En suivant ce guide, vous disposez désormais d’une implémentation complète et fonctionnelle de hCaptcha. Par défaut, hCaptcha prend en charge plusieurs widgets par page et la localisation automatique.
Si vous êtes intéressé par une implémentation plus avancée impliquant des rappels JavasSript, un rendu explicite, des thèmes alternatifs ou une localisation explicite, consultez la section suivante sur la configuration.
Et si vous rencontrez des problèmes pour faire fonctionner hCaptcha sur votre site, ou si vous souhaitez lancer un pilote de notre service d'entreprise pour essayer les scores des robots, les modes sans CAPTCHA, et bien plus encore, [prenez contact](mailto:support @hcaptcha.com) et nous serons heureux de vous aider.