Access Tags

Przegląd

Nie każda treść jest dla wszystkich: dokumenty tylko dla członków, materiały dla konkretnego regionu, zasoby płatnych pakietów. Access Tags pozwala jednemu chatbotowi bezpiecznie obsługiwać różne grupy odbiorców. Nadajesz elementowi wiedzy tag i od tej chwili element jest niewidoczny dla każdego odwiedzającego — poza tymi, których strona przedstawia ten tag, podpisany przez Twój własny serwer. Ograniczenie jest egzekwowane w naszym zapytaniu wyszukującym, zanim model AI w ogóle weźmie udział. Odwiedzający bez tagu nie wydobędzie treści sprytnymi pytaniami, bo dla niego nigdy nie została pobrana.

Jak to działa

1. Ty tagujesz elementy wiedzy - na stronie Access Tags albo bezpośrednio przez API; elementy bez tagów nadal działają dla wszystkich
2. Twój serwer podpisuje tagi każdego odwiedzającego - gdy zalogowany członek wczytuje Twoją stronę, Twój back-end ustala jego uprawnienia i podpisuje je tajnym kluczem, który posiadasz tylko Ty
3. Widżet wysyła podpisane poświadczenie - podróżuje z każdą wiadomością na czacie; przeglądarka jedynie je przenosi i nie może go zmienić bez zniszczenia podpisu
4. My weryfikujemy i filtrujemy - ważny podpis odblokowuje elementy z pasującymi tagami; brakujące, zmienione lub wygasłe poświadczenie oznacza, że odwiedzający dostaje tylko treści publiczne

Konfiguracja

Włącz funkcję na stronie Access Tags w swoim panelu — klucz podpisujący zostanie wygenerowany za Ciebie. Przechowuj go tylko na swoim serwerze; każdy, kto go ma, może tworzyć ważne poświadczenia.

Otaguj treści na tej samej stronie albo podczas przesyłania elementów przez API:

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

Następnie niech Twój serwer umieści podpisane poświadczenie obok snippetu widżetu. Podpisywana wiadomość to lista tagów rozdzielonych przecinkami, połączona pionową kreską z czasem wygaśnięcia, jeśli go używasz:

<?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>

Ten sam podpis w Node.js i Pythonie:

// 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()

Bez czasu wygaśnięcia podpisujesz sam ciąg tagów. Z czasem wygaśnięcia poświadczenie przestaje działać w chwili jego upływu — przydatne, gdy uprawnienia można odebrać, bo odwiedzający musi przeładować stronę, którą kontrolujesz, aby dostać świeże poświadczenie.

Co jest gwarantowane

• Egzekwowanie po stronie serwera - filtr działa wewnątrz naszego zapytania do bazy przy wyszukiwaniu; dla nieautoryzowanych odwiedzających elementy z tagami nie trafiają do kontekstu AI, więc nie ma czemu wyciec
• Wszędzie fail-closed - brak podpisu, zły podpis, wygasłe poświadczenie, wyłączona funkcja, obniżony plan: w każdym z tych przypadków odwiedzający dostaje wyłącznie treści publiczne, nigdy więcej
• Przeglądarka nie podrobi dostępu - edycja tagów w narzędziach deweloperskich niszczy podpis; klucz posiada tylko Twój serwer
• Twoja logika uprawnień pozostaje Twoja - nigdy nie wiemy, jak decydujesz, kto dostaje który tag; sprawdzamy tylko, że potwierdził to Twój serwer

Warto wiedzieć

• Access Tags to autoryzacja, User Context to personalizacja - użyj User Context, aby opowiedzieć AI o członku; użyj Access Tags, aby kontrolować, z jakiej wiedzy AI może korzystać
• Zaindeksowana treść witryny jest zawsze publiczna - pochodzi z Twojej publicznej strony, więc nie ma czego ograniczać; tagi dotyczą elementów tekstowych, plików i API
• Odwiedzającemu wystarczy jeden pasujący tag - element z dwoma tagami jest dostępny dla odwiedzającego posiadającego którykolwiek z nich
• Nowy klucz unieważnia wszystkie stare poświadczenia - zrób to, jeśli klucz mógł wyciec, a potem zaktualizuj strony, by podpisywały nowym
• Nazwy tagów zależą od Ciebie - do 20 na element, po 50 znaków, bez przecinków i pionowych kresek; nigdy nie pojawiają się w czacie widocznym dla odwiedzających