Guide pas à pas

Avant de commencer

• Vos pages sont servies en HTTPS.
• Vous pouvez modifier la politique CSP de vos pages, si elles en ont une.
• Vous avez un compte du tableau de bord, créé depuis votre invitation : l’accès se fait pour l’instant sur liste d’attente.
• Vous connaissez chaque nom d’hôte qui porte un formulaire : www.exemple.ch et exemple.ch sont deux noms.

Étape 1. Créer le site et les clés

1. Créez votre compte depuis l’invitation et confirmez votre adresse e-mail : tant qu’elle ne l’est pas, le tableau de bord ne propose pas d’ajouter un site. Juste après la création du compte, activez la vérification en deux étapes, obligatoire : prévoyez une application d’authentification sur votre téléphone.
2. Choisissez « Ajouter un site » : un nom, puis le nom d’hôte de vos pages.
3. À la création, le tableau de bord montre une seule fois un « Secret de signature (base64) » et un « Sel (base64) ». Ils servent au SDK Node, que ce parcours n’utilise pas ; copiez-les quand même dans votre gestionnaire de secrets avant de quitter la page : ils ne seront plus jamais affichés.
4. Ouvrez l’onglet « Clés » du site. L’« Identifiant public du site » (32 caractères) est la clé de site : c’est elle que porte la balise. Choisissez « Créer une clé », avec l’environnement « Production » et l’usage « Vérification serveur ». La clé (64 caractères) est montrée une seule fois.
5. Dans l’onglet « Paramètres », vérifiez les « Noms d’hôte » : la liste doit contenir chacun des noms de vos pages (noms d’hôte déclarés). Faites-le avant l’étape 2 : dès que la balise est posée, une page servie sous un nom non déclaré reçoit des jetons que la vérification refuse, collecte allumée ou éteinte.

Aucun préfixe ne dit de quel type est une clé : notez-le à la création, et comptez les caractères avant de coller une clé dans une page. À la fin de l’étape, vous avez la clé de site et un secret de vérification. Un site naît avec la « Collecte du navigateur » éteinte : c’est voulu, voir l’étape 6. Le détail est sur la page des clés et environnements de test.

Étape 2. Poser le script sur la page

1. La balise, dans le <head> de chaque page qui porte un formulaire. data-site reçoit la clé de site, jamais un secret de 64 caractères (la balise).
2. La politique CSP, si vous en avez une : essayez-la d’abord en Content-Security-Policy-Report-Only ; les violations signalées nomment la directive à compléter. Une page qui impose Trusted Types ajoute la politique antisy à sa directive (politique CSP).
3. Le formulaire : rien à écrire. Un formulaire POST vers votre propre site est couvert tel quel. À l’envoi, le script retient l’envoi, remplit le champ caché antisy-token (il le crée s’il n’existe pas) et reprend l’envoi, au plus après 6 secondes : si Antisy ne répond pas, le formulaire part quand même, sans jeton (le champ est alors absent, ou vide s’il existait déjà).
4. Les formulaires que le script ne couvre pas partent sans jeton. Un POST vers une autre origine (un sous-domaine en est une) ou un GET se couvre avec l’attribut data-antisy. Un envoi par fetch ou par form.submit(), ou vers une autre fenêtre, demande antisy.token() depuis la page. La liste complète est dans quels formulaires sont couverts.
5. Un formulaire que vous ne protégez pas (recherche en POST, lettre d’information présente sur toutes les pages) se marque data-antisy="off" (exclure un formulaire).
6. Si votre page appelait déjà antisy.token() pour un formulaire POST vers votre site, retirez l’appel, ou posez data-antisy="off" si vous gardez la main : sinon la page fait un second dépôt et le premier envoi est plus lent (antisy.token()).

Étape 3. Vérifier le jeton côté serveur

1. Le secret « Vérification serveur » de l’étape 1 va dans une variable d’environnement de votre serveur, et il n’en sort que dans le corps de la requête, nulle part ailleurs (la requête).
2. Copiez l’exemple de votre langage : curl et Node dans le démarrage rapide, PHP, Python et Go dans la page vérifier un jeton. Chacun applique les mêmes règles : contrôler le jeton avant l’appel, n’accepter que sur success à true, attendre 3 secondes au plus, ne suivre aucune redirection.
3. N’envoyez pas remoteip : il est ignoré.
4. Faites un seul appel par jeton : un jeton est valable 60 secondes et ne se vérifie qu’une fois. Pour pouvoir rejouer un appel qui a peut-être abouti sans que vous ayez lu la réponse, générez sur votre serveur une idempotency_key (un UUID) avant le premier appel, et envoyez-la dès ce premier appel ; renvoyez ensuite la même requête, avec la même clé, dans les 60 secondes. Une clé ajoutée au seul second appel ne reprend rien : si le premier a abouti, le jeton est déjà consommé, et la réponse est un refus (timeout-or-duplicate). Les exemples cités plus haut n’envoient pas de clé ; ne la reprenez jamais de la requête du visiteur (durée de validité et usage unique).

Étape 4. Choisir la conduite en cas de panne

Ce que votre serveur fait quand Antisy ne répond pas est un choix de votre part, route par route. Les exemples appliquent la règle de la page quand l’API ne répond pas.

Panne, délai dépassé, réponse 5xx

Les exemples laissent passer l’envoi et le journalisent : une panne chez Antisy ne doit pas coûter vos visiteurs.

429, ou 503 qui porte Retry-After

Les exemples laissent passer par défaut. Mais un attaquant peut provoquer ces réponses par le volume, et c’est alors que ses envois passent avec les vôtres. Pour un formulaire sensible, refusez : pour le 429, mettez deny dans la constante de l’exemple ; pour le 503 qui porte Retry-After, que les exemples traitent comme toute réponse 5xx, ajoutez ce cas avant celui des 5xx, avec la même valeur (vérifier un jeton). C’est le choix protecteur, au prix de refuser quelques visiteurs légitimes pendant une saturation.

400, 401, 413, 415 et tout autre 4xx

Ne laissez jamais passer : c’est un défaut de votre appel. Journalisez-le comme un bug à corriger, et refusez l’envoi, qui n’a pas été vérifié.

Étape 5. Tester avec une clé de test

• Dans « Clés », créez une clé d’environnement « Test (non comptée dans les statistiques) » et d’usage « Vérification serveur ». Un site en porte au plus 2 ; celles de toute votre organisation partagent 1 000 appels par jour et, à ce jour, 2 500 par mois.
• Les deux clés de site factices « allow » et « deny » donnent un verdict connu d’avance. Dans une page de développement, mettez-en une dans data-site à la place de l’identifiant public du site : le script rend un jeton fixe, que votre serveur vérifie avec le secret de test, sans nom d’hôte à déclarer. Sans navigateur réel (intégration continue), la recette de la page clés de test donne le même jeton.

Étape 6. Passer en production

1. Mettez sur votre serveur le secret « Production » créé à l’étape 1 à la place du secret de test. Pour changer un secret sans coupure, suivez créer, copier, révoquer.
2. Relisez, ligne à ligne, la liste « Avant d’allumer la collecte » de la page si le script ne tourne pas.
3. Allumez la « Collecte du navigateur » (onglet « Paramètres »). Le tableau de bord demande de cocher chaque vérification avant « Allumer la collecte ». Allumée, l’absence de jeton ne passe plus, quel que soit le mode de vérification : un formulaire que le script ne couvre pas et dont la page n’a pas appelé antisy.token() est refusé, et un script bloqué refuse tous les visiteurs, humains compris. Pendant le pilote, l’allumage se décide avec Antisy ; si le tableau de bord affiche « Tenue par Antisy », il ne propose pas de l’allumer : écrivez au support.
4. Faites un envoi à la main par chaque formulaire protégé, depuis votre page : chacun doit être accepté. Le verdict se lit dans l’onglet « Événements ». Si l’un est refusé, voyez l’étape 8.
5. Si de vrais visiteurs sont refusés, vérifiez d’abord les noms d’hôte déclarés (étape 1). Le bouton « Éteindre la collecte » agit en un clic, à tout moment, et ne change rien d’autre : il ne rattrape que les envois sans jeton. Un refus avec un jeton présent (nom d’hôte non déclaré, appareil trop lent pour finir le calcul) n’en dépend pas. Puis écrivez au support.

Le mode de vérification du site (Strict, Équilibré, Permissif) se règle aussi dans « Paramètres » : il ne change que le moment où un visiteur douteux ne passe pas (à quel point refuser). Le verdict reste allow ou deny, et ce qui ne passe jamais, quel que soit le mode, est sur la page ce qui ne passe jamais.

Étape 7. Lire le tableau de bord

Un site a quatre onglets : « Aperçu », « Événements », « Clés » et « Paramètres ».

Aperçu

Le volume de vérifications sur la période, les volumes qui « Passent » et qui « Ne passent pas », et « Refus par catégorie ».

Refus par catégorie

Deux catégories seulement : « Jeton absent ou invalide » et « Autres refus ». Les totaux sont arrondis à la dizaine (le tableau dit « environ »), non publiés sous 20 (« moins de 20 »), et publiés 48 heures après la fin du jour : un jour qui n’est pas encore publié affiche « Publié 48 h après la fin du jour », rien n’est cassé.

Les deux colonnes ne s’additionnent pas exactement et ne disent rien d’une vérification en particulier.

Événements

Les vérifications récentes, avec le verdict, l’horodatage, le type d’événement et la famille du navigateur. Pour retrouver une tentative précise, gardez dans vos journaux l’event_id de la réponse de la vérification : le support en aura besoin.

Étape 8. Un vrai visiteur est refusé

Antisy ne donne aucune raison de refus, ni dans la réponse ni dans le tableau de bord. Vous procédez par élimination, du plus fréquent au plus rare.

1. Le jeton est-il parti ? Dans la console réseau, le champ antisy-token (ou l’en-tête x-antisy-token) est-il rempli dans la requête envoyée à votre serveur ? Sinon : si le script ne tourne pas (politique CSP, bloqueur de publicité, page en HTTP, formulaire non couvert).
2. Le nom d’hôte de la page est-il déclaré ? Depuis un nom absent de la liste (www. oublié, ou le domaine nu), le champ antisy-token part rempli, avec l’air d’un vrai jeton, et la vérification le refuse, collecte allumée ou éteinte (noms d’hôte déclarés).
3. Votre serveur lit-il le bon champ, avec le bon secret ? Le champ s’appelle antisy-token et se transmet tel qu’il est arrivé, sans le tronquer. Un secret absent ou refusé (missing-input-secret, invalid-input-secret) fait refuser tous les visiteurs : journalisez ces codes (codes d’erreur).
4. Le visiteur a-t-il laissé la page ouverte longtemps, ou envoyé deux fois ? Un jeton expiré ou déjà vérifié rend timeout-or-duplicate. Votre message de refus doit dire « réessayez » : un nouvel essai obtient un jeton neuf.
5. L’appareil est-il très lent ? Un appareil qui n’achève pas à temps le calcul en arrière-plan est refusé comme pour un jeton invalide ; un nouvel essai tire un nouveau calcul (si le script ne tourne pas).
6. Votre liste d’autorisation ne dispense pas du jeton : un jeton invalide, rejoué ou expiré est refusé même pour un identifiant autorisé, et un jeton absent aussi quand la collecte est allumée.
7. Le mode « Permissif » de « Paramètres » refuse moins ; revenez à « Équilibré » si des robots passent.
8. Si le problème persiste, écrivez au support, ci-dessous.

Qui contacter

Écrivez à support@antisy.com. Joignez :

• la date et l’heure approximatives, avec le fuseau ;
• le nom d’hôte de la page ;
• l’event_id de la réponse de la vérification : c’est avec lui qu’Antisy retrouve une tentative ;
• ce que vous avez déjà vérifié parmi les étapes ci-dessus.

N’envoyez jamais une clé, un secret ni une donnée personnelle d’un visiteur (adresse e-mail, mot de passe) : Antisy n’en a pas besoin.

Le support fait aussi, sur votre demande écrite, ce que le tableau de bord ne fait pas : remplacer un secret de signature, perdu ou à changer, et poser ou retirer une liste d’autorisation ou de blocage pour votre site.

Prêt à ouvrir

• Site créé, noms d’hôte déclarés, secrets copiés (étape 1).
• Balise et politique CSP posées ; chaque formulaire est couvert, marqué data-antisy, pris en charge par antisy.token() ou exclu par data-antisy="off" (étape 2).
• Vérification serveur en place, avec le secret dans le corps de la requête (étape 3).
• Conduite en cas de panne choisie, route par route (étape 4).
• Essai fait avec une clé de test, qui n’est plus sur le serveur de production (étapes 5 et 6).
• Collecte allumée, un envoi à la main par formulaire protégé accepté (étape 6).
• L’adresse du support est connue de vos équipes (étape 8).