Schritt-für-Schritt-Anleitung

Bevor Sie beginnen

• Ihre Seiten werden über HTTPS ausgeliefert.
• Sie können die CSP-Richtlinie Ihrer Seiten ändern, falls sie eine haben.
• Sie haben ein Konto im Dashboard (auf Französisch), angelegt über Ihre Einladung: Der Zugang erfolgt vorerst über eine Warteliste.
• Sie kennen jeden Hostnamen, der ein Formular trägt: www.exemple.ch und exemple.ch sind zwei Namen.

Schritt 1. Website und Schlüssel anlegen

1. Legen Sie Ihr Konto über die Einladung an und bestätigen Sie Ihre E-Mail-Adresse: Solange sie nicht bestätigt ist, bietet das Dashboard nicht an, eine Website hinzuzufügen. Gleich nach dem Anlegen des Kontos aktivieren Sie die Zwei-Faktor-Prüfung, die Pflicht ist: Halten Sie eine Authentifizierungs-App auf Ihrem Telefon bereit.
2. Wählen Sie « Ajouter un site » (Website hinzufügen): einen Namen, dann den Hostnamen Ihrer Seiten.
3. Bei der Erstellung zeigt das Dashboard ein einziges Mal ein « Secret de signature (base64) » (Signatur-Secret) und ein « Sel (base64) » (Salt). Sie dienen dem Node-SDK, das dieser Weg nicht verwendet; kopieren Sie sie trotzdem in Ihren Secret-Manager, bevor Sie die Seite verlassen: Sie werden nie wieder angezeigt.
4. Öffnen Sie den Tab « Clés » (Schlüssel) der Website. Die « Identifiant public du site » (32 Zeichen) ist der Site-Key: Ihn trägt das Script-Tag. Wählen Sie « Créer une clé » (Schlüssel erstellen), mit der Umgebung « Production » und der Verwendung « Vérification serveur » (Prüfung auf dem Server). Der Schlüssel (64 Zeichen) wird ein einziges Mal angezeigt.
5. Prüfen Sie im Tab « Paramètres » (Einstellungen) die « Noms d’hôte » (Hostnamen): Die Liste muss jeden Namen Ihrer Seiten enthalten (deklarierte Hostnamen). Tun Sie das vor Schritt 2: Sobald das Script-Tag gesetzt ist, erhält eine Seite unter einem nicht deklarierten Namen Token, die die Prüfung ablehnt, ob die Erfassung an oder aus ist.

Kein Präfix sagt, welcher Art ein Schlüssel ist: Notieren Sie es bei der Erstellung, und zählen Sie die Zeichen, bevor Sie einen Schlüssel in eine Seite einfügen. Am Ende des Schritts haben Sie den Site-Key und ein Verifizierungs-Secret. Eine Website beginnt mit ausgeschalteter « Collecte du navigateur » (Erfassung im Browser): Das ist gewollt, siehe Schritt 6. Die Einzelheiten stehen auf der Seite Schlüssel und Testumgebungen.

Schritt 2. Das Script auf die Seite setzen

1. Das Script-Tag, im <head> jeder Seite, die ein Formular trägt. data-site erhält den Site-Key, nie ein Secret mit 64 Zeichen (das Script-Tag).
2. Die CSP-Richtlinie, falls Sie eine haben: Probieren Sie sie zuerst als Content-Security-Policy-Report-Only aus; die gemeldeten Verstösse nennen die Direktive, die zu ergänzen ist. Eine Seite, die Trusted Types verlangt, fügt ihrer Direktive die Richtlinie antisy hinzu (CSP-Richtlinie).
3. Das Formular: nichts zu schreiben. Ein POST-Formular an Ihre eigene Website ist so, wie es ist, abgedeckt. Beim Absenden hält das Script die Übermittlung zurück, füllt das versteckte Feld antisy-token aus (es legt es an, wenn es nicht existiert) und setzt die Übermittlung fort, spätestens nach 6 Sekunden: Antwortet Antisy nicht, wird das Formular trotzdem gesendet, ohne Token (das Feld fehlt dann, oder es ist leer, wenn es schon existierte).
4. Die Formulare, die das Script nicht abdeckt, werden ohne Token gesendet. Ein POST an eine andere Origin (eine Subdomain ist eine) oder ein GET wird mit dem Attribut data-antisy abgedeckt. Eine Übermittlung per fetch oder per form.submit(), oder an ein anderes Fenster, verlangt antisy.token() aus der Seite. Die vollständige Liste steht unter welche Formulare abgedeckt sind.
5. Ein Formular, das Sie nicht schützen (Suche per POST, Newsletter auf allen Seiten), wird mit data-antisy="off" markiert (ein Formular ausschliessen).
6. Rief Ihre Seite schon antisy.token() für ein POST-Formular an Ihre Website auf, entfernen Sie den Aufruf, oder setzen Sie data-antisy="off", wenn Sie die Kontrolle behalten: Sonst macht die Seite eine zweite Hinterlegung, und die erste Übermittlung ist langsamer (antisy.token()).

Schritt 3. Das Token auf dem Server prüfen

1. Das Secret « Vérification serveur » aus Schritt 1 kommt in eine Umgebungsvariable Ihres Servers, und es verlässt sie nur im Body der Anfrage, nirgends sonst (die Anfrage).
2. Kopieren Sie das Beispiel Ihrer Sprache: curl und Node im Schnellstart, PHP, Python und Go auf der Seite ein Token prüfen. Jedes wendet dieselben Regeln an: das Token vor dem Aufruf prüfen, nur bei success gleich true annehmen, höchstens 3 Sekunden warten, keiner Weiterleitung folgen.
3. Senden Sie remoteip nicht: Es wird ignoriert.
4. Machen Sie einen einzigen Aufruf pro Token: Ein Token ist 60 Sekunden gültig und lässt sich nur einmal prüfen. Um einen Aufruf wiederholen zu können, der vielleicht durchging, ohne dass Sie die Antwort gelesen haben, erzeugen Sie auf Ihrem Server einen idempotency_key (eine UUID) vor dem ersten Aufruf und senden ihn schon bei diesem ersten Aufruf mit; senden Sie danach dieselbe Anfrage mit demselben Schlüssel innerhalb von 60 Sekunden erneut. Ein Schlüssel, der erst beim zweiten Aufruf hinzukommt, holt nichts zurück: War der erste erfolgreich, ist das Token schon verbraucht, und die Antwort ist eine Ablehnung (timeout-or-duplicate). Die oben genannten Beispiele senden keinen Schlüssel; übernehmen Sie ihn nie aus der Anfrage des Besuchers (Gültigkeitsdauer und einmalige Verwendung).

Schritt 4. Das Verhalten bei einem Ausfall wählen

Was Ihr Server tut, wenn Antisy nicht antwortet, ist Ihre Wahl, Route für Route. Die Beispiele wenden die Regel der Seite wenn die API nicht antwortet an.

Ausfall, Zeitlimit überschritten, Antwort 5xx

Die Beispiele lassen die Übermittlung durch und protokollieren sie: Ein Ausfall bei Antisy darf Sie nicht Ihre Besucher kosten.

429, oder 503 mit Retry-After

Die Beispiele lassen standardmässig durch. Aber ein Angreifer kann diese Antworten durch Masse auslösen, und genau dann kommen seine Übermittlungen mit Ihren durch. Für ein sensibles Formular lehnen Sie ab: für den 429 setzen Sie deny in die Konstante des Beispiels; für den 503 mit Retry-After, den die Beispiele wie jede Antwort 5xx behandeln, fügen Sie diesen Fall vor dem der 5xx ein, mit demselben Wert (ein Token prüfen). Das ist die schützende Wahl, um den Preis, während einer Überlastung einige legitime Besucher abzulehnen.

400, 401, 413, 415 und jeder andere 4xx

Lassen Sie nie durch: Das ist ein Fehler Ihres Aufrufs. Protokollieren Sie ihn als zu behebenden Fehler, und lehnen Sie die Übermittlung ab, die nicht geprüft wurde.

Schritt 5. Mit einem Testschlüssel testen

• Erstellen Sie unter « Clés » einen Schlüssel mit der Umgebung « Test (non comptée dans les statistiques) » (nicht in den Statistiken gezählt) und der Verwendung « Vérification serveur ». Eine Website hat höchstens 2 davon; die Ihrer ganzen Organisation teilen sich 1’000 Aufrufe pro Tag und, Stand heute, 2’500 pro Monat.
• Die beiden Dummy-Site-Keys « allow » und « deny » liefern ein im Voraus bekanntes Ergebnis. Setzen Sie in einer Entwicklungsseite einen davon in data-site, anstelle der öffentlichen Kennung der Website: Das Script liefert ein festes Token, das Ihr Server mit dem Test-Secret prüft, ohne einen Hostnamen zu deklarieren. Ohne echten Browser (Continuous Integration) liefert das Vorgehen der Seite Testschlüssel dasselbe Token.

Schritt 6. In Produktion gehen

1. Setzen Sie auf Ihrem Server das in Schritt 1 erstellte Secret « Production » anstelle des Test-Secrets ein. Um ein Secret ohne Unterbruch zu wechseln, folgen Sie erstellen, kopieren, widerrufen.
2. Lesen Sie, Zeile für Zeile, die Liste « Bevor Sie die Erfassung einschalten » auf der Seite wenn das Script nicht läuft.
3. Schalten Sie die « Collecte du navigateur » (Erfassung im Browser) ein (Tab « Paramètres »). Das Dashboard verlangt, jede Prüfung anzukreuzen, bevor « Allumer la collecte » (Erfassung einschalten) möglich ist. Ist sie an, kommt ein fehlendes Token nicht mehr durch, unabhängig vom Prüfmodus: Ein Formular, das das Script nicht abdeckt und dessen Seite antisy.token() nicht aufgerufen hat, wird abgelehnt, und ein blockiertes Script lehnt alle Besucher ab, Menschen eingeschlossen. Während des Pilots wird das Einschalten mit Antisy entschieden; zeigt das Dashboard « Tenue par Antisy » (von Antisy gehalten), bietet es das Einschalten nicht an: Schreiben Sie dem Support.
4. Machen Sie eine Übermittlung von Hand über jedes geschützte Formular, von Ihrer Seite aus: Jede muss angenommen werden. Das Ergebnis steht im Tab « Événements » (Ereignisse). Wird eine abgelehnt, siehe Schritt 8.
5. Werden echte Besucher abgelehnt, prüfen Sie zuerst die deklarierten Hostnamen (Schritt 1). Solange die Erfassung an ist, wirkt die Schaltfläche « Éteindre la collecte » (Erfassung ausschalten) mit einem Klick, jederzeit, und ändert nichts anderes: Sie fängt nur die Übermittlungen ohne Token auf. Eine Ablehnung mit vorhandenem Token (nicht deklarierter Hostname, Gerät zu langsam, um die Berechnung abzuschliessen) hängt nicht davon ab. Schreiben Sie dann dem Support.

Der Prüfmodus der Website (Strict, Équilibré, Permissif: streng, ausgewogen, nachsichtig) wird ebenfalls unter « Paramètres » eingestellt: Er ändert nur den Moment, ab dem ein zweifelhafter Besucher nicht mehr durchkommt (wie streng ablehnen). Das Ergebnis bleibt allow oder deny, und was in keinem Modus durchkommt, steht auf der Seite was nie durchkommt.

Schritt 7. Das Dashboard lesen

Eine Website hat vier Tabs: « Aperçu » (Übersicht), « Événements » (Ereignisse), « Clés » (Schlüssel) und « Paramètres » (Einstellungen).

Aperçu

Das Volumen der Prüfungen im Zeitraum, die Volumen, die « Passent » (durchkommen) und die « Ne passent pas » (nicht durchkommen), und « Refus par catégorie » (Ablehnungen nach Kategorie).

Refus par catégorie

Nur zwei Kategorien: « Jeton absent ou invalide » (Token fehlt oder ungültig) und « Autres refus » (andere Ablehnungen). Die Summen sind auf den Zehner gerundet (die Tabelle sagt « environ », etwa), unter 20 nicht veröffentlicht (« moins de 20 », weniger als 20) und 48 Stunden nach Ende des Tages veröffentlicht: Ein Tag, der noch nicht veröffentlicht ist, zeigt « Publié 48 h après la fin du jour » (48 h nach Ende des Tages veröffentlicht), nichts ist kaputt.

Die beiden Spalten ergeben zusammen nicht genau die Summe und sagen nichts über eine einzelne Prüfung.

Événements

Die letzten Prüfungen, mit dem Ergebnis, dem Zeitstempel, der Art des Ereignisses und der Familie des Browsers. Um einen bestimmten Versuch wiederzufinden, bewahren Sie in Ihren Protokollen die event_id aus der Antwort der Prüfung auf: Der Support braucht sie.

Schritt 8. Ein echter Besucher wird abgelehnt

Antisy nennt keinen Grund für eine Ablehnung, weder in der Antwort noch im Dashboard. Sie gehen im Ausschlussverfahren vor, vom häufigsten zum seltensten Fall.

1. Wurde das Token gesendet? Ist in der Netzwerkkonsole das Feld antisy-token (oder der Header x-antisy-token) in der Anfrage an Ihren Server ausgefüllt? Wenn nicht: wenn das Script nicht läuft (CSP-Richtlinie, Werbeblocker, Seite über HTTP, nicht abgedecktes Formular).
2. Ist der Hostname der Seite deklariert? Von einem Namen, der nicht in der Liste steht (www. vergessen, oder die nackte Domain), wird das Feld antisy-token ausgefüllt gesendet, mit dem Aussehen eines echten Tokens, und die Prüfung lehnt es ab, ob die Erfassung an oder aus ist (deklarierte Hostnamen).
3. Liest Ihr Server das richtige Feld, mit dem richtigen Secret? Das Feld heisst antisy-token und wird so weitergegeben, wie es angekommen ist, ohne es zu kürzen. Ein fehlendes oder abgelehntes Secret (missing-input-secret, invalid-input-secret) lässt alle Besucher ablehnen: Protokollieren Sie diese Codes (Fehlercodes).
4. Hat der Besucher die Seite lange offen gelassen oder zweimal gesendet? Ein abgelaufenes oder schon geprüftes Token ergibt timeout-or-duplicate. Ihre Ablehnungsmeldung muss « versuchen Sie es erneut » sagen: Ein neuer Versuch erhält ein frisches Token.
5. Ist das Gerät sehr langsam? Ein Gerät, das die Berechnung im Hintergrund nicht rechtzeitig abschliesst, wird abgelehnt wie bei einem ungültigen Token; ein neuer Versuch startet eine neue Berechnung (wenn das Script nicht läuft).
6. Ihre Zulassungsliste befreit nicht vom Token: Ein ungültiges, wiederholtes oder abgelaufenes Token wird auch für eine zugelassene Kennung abgelehnt, und ein fehlendes Token ebenfalls, wenn die Erfassung an ist.
7. Der Modus « Permissif » (nachsichtig) unter « Paramètres » lehnt weniger ab; kehren Sie zu « Équilibré » (ausgewogen) zurück, wenn Bots durchkommen.
8. Besteht das Problem weiter, schreiben Sie dem Support, unten.

Wen kontaktieren

Schreiben Sie an support@antisy.com. Der Support antwortet auf Französisch und Englisch. Fügen Sie bei:

• das ungefähre Datum und die ungefähre Uhrzeit, mit der Zeitzone;
• den Hostnamen der Seite;
• die event_id aus der Antwort der Prüfung: Mit ihr findet Antisy einen Versuch wieder;
• was Sie unter den obigen Schritten schon geprüft haben.

Senden Sie nie einen Schlüssel, ein Secret oder persönliche Daten eines Besuchers (E-Mail-Adresse, Passwort): Antisy braucht sie nicht.

Der Support erledigt auf Ihren schriftlichen Wunsch auch, was das Dashboard nicht kann: ein verlorenes oder zu wechselndes Signatur-Secret ersetzen und eine Zulassungs- oder Sperrliste für Ihre Website setzen oder entfernen.

Bereit zum Öffnen

• Website angelegt, Hostnamen deklariert, Secrets kopiert (Schritt 1).
• Script-Tag und CSP-Richtlinie gesetzt; jedes Formular ist abgedeckt, mit data-antisy markiert, von antisy.token() übernommen oder mit data-antisy="off" ausgeschlossen (Schritt 2).
• Prüfung auf dem Server eingerichtet, mit dem Secret im Body der Anfrage (Schritt 3).
• Verhalten bei einem Ausfall gewählt, Route für Route (Schritt 4).
• Versuch mit einem Testschlüssel gemacht, der nicht mehr auf dem Produktionsserver ist (Schritte 5 und 6).
• Erfassung eingeschaltet, eine Übermittlung von Hand pro geschütztem Formular angenommen (Schritt 6).
• Die Adresse des Supports ist Ihren Teams bekannt (Schritt 8).