Access Tags

Übersicht

Nicht alle Inhalte sind für alle bestimmt: Dokumente nur für Mitglieder, regionsspezifisches Material, Ressourcen für zahlende Stufen. Mit Access Tags bedient ein Chatbot verschiedene Zielgruppen sicher. Sie versehen einen Wissenseintrag mit einem Tag, und ab diesem Moment ist der Eintrag für jeden Besucher unsichtbar — außer für jene, deren Seite dieses Tag vorlegt, signiert von Ihrem eigenen Server. Die Beschränkung wird in unserer Abfrage durchgesetzt, bevor das KI-Modell überhaupt beteiligt ist. Ein Besucher ohne das Tag kann den Inhalt nicht durch geschicktes Fragen herauslocken, denn für ihn wurde er gar nicht erst abgerufen.

So funktioniert es

1. Sie taggen Wissenseinträge - auf der Access-Tags-Seite oder direkt über die API; Einträge ohne Tags funktionieren weiterhin für alle
2. Ihr Server signiert die Tags jedes Besuchers - wenn ein eingeloggtes Mitglied Ihre Seite lädt, bestimmt Ihr Backend seine Berechtigungen und signiert sie mit einem geheimen Schlüssel, den nur Sie besitzen
3. Das Widget sendet den signierten Nachweis - er wird mit jeder Chat-Nachricht übertragen; der Browser transportiert ihn nur und kann ihn nicht verändern, ohne die Signatur zu zerstören
4. Wir prüfen und filtern - eine gültige Signatur schaltet Einträge mit passenden Tags frei; ein fehlender, manipulierter oder abgelaufener Nachweis bedeutet, dass der Besucher nur öffentliche Inhalte erhält

Einrichtung

Schalten Sie die Funktion auf der Access-Tags-Seite in Ihrem Dashboard ein — ein Signaturschlüssel wird für Sie generiert. Bewahren Sie ihn nur auf Ihrem Server auf; wer ihn besitzt, kann gültige Nachweise erstellen.

Taggen Sie Ihre Inhalte entweder auf derselben Seite oder beim Übertragen von Einträgen über die API:

POST /api/v1/knowledge/text/
{
  "title": "Members-only price list",
  "content": "...",
  "website_id": "123",
  "access_tags": ["premium"]
}

Lassen Sie dann Ihren Server den signierten Nachweis neben dem Widget-Snippet ausgeben. Signiert wird die kommagetrennte Tag-Liste, verbunden mit einem senkrechten Strich und der Ablaufzeit, wenn Sie eine verwenden:

<?php
$tags    = "members,premium";          // this visitor's entitlements
$expires = time() + 3600;              // unix seconds, optional but recommended
$sig     = hash_hmac("sha256", $tags . "|" . $expires, $SECRET);
?>
<script>
window.Asyntai = window.Asyntai || {};
window.Asyntai.accessTags = "<?php echo $tags; ?>";
window.Asyntai.accessTagsExpires = "<?php echo $expires; ?>";
window.Asyntai.accessTagsSignature = "<?php echo $sig; ?>";
</script>

Dieselbe Signatur in Node.js und Python:

// Node.js
const crypto = require("crypto");
const sig = crypto.createHmac("sha256", SECRET)
                  .update(tags + "|" + expires).digest("hex");

# Python
import hmac, hashlib
sig = hmac.new(SECRET.encode(), f"{tags}|{expires}".encode(),
               hashlib.sha256).hexdigest()

Ohne Ablaufzeit signieren Sie nur die Tag-Zeichenkette selbst. Mit Ablaufzeit funktioniert ein Nachweis ab dem Ablaufmoment nicht mehr — nützlich, wenn Berechtigungen entzogen werden können, denn der Besucher muss eine von Ihnen kontrollierte Seite neu laden, um einen frischen Nachweis zu erhalten.

Tag-Logik

Die Tags eines Eintrags werden mit UND verknüpft: der Eintrag ist nur abrufbar, wenn jeder Tag darauf im Nachweis des Besuchers vorkommt. Der Nachweis eines Besuchers darf beliebig viele Berechtigungen enthalten, und der Abgleich erfolgt über alle gleichzeitig.

UND ist Absicht. Bei Irgendein-Abgleich würde ein zweiter Tag auf einem Eintrag erweitern, wer ihn sehen darf; das Einschränken eines Dokuments auf zwei Gruppen würde es also beiden vollständig freigeben. Bei Alle-Abgleich kann jeder zusätzliche Tag nur weiter einschränken, sodass ein Fehler in die sichere Richtung fällt.

„Eines von mehreren“ ausdrücken

Lassen Sie die Dimension am Eintrag weg. Wenn der Nachweis jedes Besuchers seine Region enthält, ist ein Dokument ohne Regions-Tag für alle Regionen verfügbar, während seine übrigen Tags weiterhin gelten. Ein Eintrag mit nur premium bedeutet also „jede Region, nur Premium-Abonnenten“.

Für eine echte dimensionsübergreifende Auswahl — etwa Nord-mit-Basis oder Süd-mit-Premium und sonst nichts — fügen Sie den Eintrag zweimal mit je einer Kombination hinzu, oder geben Sie beiden Zielgruppen einen gemeinsamen Tag, den Ihr Server in ihre Nachweise aufnimmt.

Grenzwerte

• Bis zu 20 Tags pro Wissenseintrag
• Bis zu 50 Tags im Nachweis eines einzelnen Besuchers
• 50 Zeichen pro Tag; Kommas und senkrechte Striche sind nicht erlaubt, da der Nachweis eine kommagetrennte Zeichenkette ist

Tags später ändern

Tags lassen sich an einem bestehenden Eintrag ersetzen, ohne ihn erneut hochzuladen. Die Änderung gilt ab der nächsten Frage — der Inhalt selbst wird nicht neu verarbeitet.

POST /api/v1/knowledge/<id>/tags/
{
  "access_tags": ["premium"]
}

Senden Sie eine leere Liste, um einen Eintrag wieder öffentlich zu machen. Sie können Tags auch von Hand auf der Access-Tags-Seite in Ihrem Dashboard bearbeiten.

Was garantiert ist

• Serverseitige Durchsetzung - der Filter läuft in unserer Datenbankabfrage beim Abruf; getaggte Einträge fehlen im Kontext der KI für nicht autorisierte Besucher, es gibt also nichts, was durchsickern könnte
• Überall fail-closed - keine Signatur, falsche Signatur, abgelaufener Nachweis, Funktion ausgeschaltet, Plan herabgestuft: in jedem dieser Fälle erhält der Besucher nur öffentliche Inhalte, niemals mehr
• Der Browser kann keinen Zugriff fälschen - das Bearbeiten der Tags in den Entwicklertools zerstört die Signatur; nur Ihr Server besitzt den Schlüssel
• Ihre Berechtigungslogik bleibt Ihre - wir erfahren nie, wie Sie entscheiden, wer welches Tag erhält; wir prüfen nur, dass Ihr Server es bestätigt hat

Gut zu wissen

• Access Tags ist Autorisierung, User Context ist Personalisierung - nutzen Sie User Context, um der KI etwas über das Mitglied mitzuteilen; nutzen Sie Access Tags, um zu steuern, auf welches Wissen die KI zugreifen darf
• Gecrawlte Website-Inhalte sind immer öffentlich - sie stammen von Ihrer öffentlichen Website, es gibt also nichts zu beschränken; Tags gelten für Text-, Datei- und API-Einträge
• Tags eines Eintrags werden mit UND verknüpft - siehe Tag-Logik oben; jeder Tag des Eintrags muss im Nachweis des Besuchers vorhanden sein
• Das Neugenerieren des Schlüssels macht alle alten Nachweise ungültig - tun Sie es, falls der Schlüssel durchgesickert sein könnte, und aktualisieren Sie dann Ihre Seiten, damit sie mit dem neuen signieren
• Tag-Namen bestimmen Sie selbst - bis zu 20 pro Eintrag, je 50 Zeichen, ohne Kommas oder senkrechte Striche; im Chat der Besucher tauchen sie nie auf