Access Tags

Přehled

Ne každý obsah je pro všechny: dokumenty jen pro členy, materiály pro konkrétní region, zdroje placených úrovní. S Access Tags obslouží jediný chatbot různá publika bezpečně. Položce přidáte tag a od té chvíle je neviditelná pro každého návštěvníka — kromě těch, jejichž stránka tento tag předloží, podepsaný vaším vlastním serverem. Omezení se vynucuje v našem vyhledávacím dotazu, ještě než se model AI vůbec zapojí. Návštěvník bez tagu obsah chytrými dotazy nevytáhne, protože pro něj nebyl nikdy načten.

Jak to funguje

1. Znalostní položky tagujete vy - na stránce Access Tags nebo přímo přes API; položky bez tagů fungují dál pro všechny
2. Váš server podepisuje tagy každého návštěvníka - když si přihlášený člen načte vaši stránku, váš back-end určí jeho oprávnění a podepíše je tajným klíčem, který máte jen vy
3. Widget odešle podepsané pověření - putuje s každou zprávou v chatu; prohlížeč je pouze přenáší a nemůže je změnit, aniž by rozbil podpis
4. My ověříme a filtrujeme - platný podpis odemkne položky s odpovídajícími tagy; chybějící, pozměněné nebo prošlé pověření znamená, že návštěvník dostane jen veřejný obsah

Nastavení

Zapněte funkci na stránce Access Tags ve své nástěnce — podpisový klíč se vám vygeneruje. Uchovávejte jej jen na svém serveru; kdokoli jej má, může vytvářet platná pověření.

Obsah otagujte buď na téže stránce, nebo při odesílání položek přes API:

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

Poté nechte svůj server vypsat podepsané pověření vedle snippetu widgetu. Podepisuje se seznam tagů oddělených čárkami, spojený svislou čarou s časem vypršení, pokud jej používáte:

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

Tentýž podpis v Node.js a Pythonu:

// 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 času vypršení podepište jen samotný řetězec tagů. S ním přestane pověření fungovat v okamžiku vypršení — hodí se, když lze oprávnění odebrat, protože návštěvník si musí znovu načíst stránku pod vaší kontrolou, aby dostal čerstvé pověření.

Logika tagů

Tagy položky se kombinují pomocí AND: položka je dostupná jen tehdy, když se každý její tag objeví v pověření návštěvníka. Pověření návštěvníka může nést libovolně mnoho oprávnění a porovnává se se všemi najednou.

AND je záměr. Při porovnání «alespoň jeden» by druhý tag na položce rozšířil, kdo ji smí vidět, takže zúžení dokumentu na dvě skupiny by ho ve skutečnosti celý zpřístupnilo oběma. Při porovnání «všechny» může každý přidaný tag jen dále omezovat, takže chyba padne na bezpečnou stranu.

Vyjádření «kterýkoli z»

Vynechte tento rozměr u položky. Pokud pověření každého návštěvníka nese jeho region, dokument bez tagu regionu je dostupný všem regionům, zatímco jeho ostatní tagy dál platí. Položka otagovaná jen jako premium tedy znamená «jakýkoli region, pouze předplatitelé premium».

Pro skutečnou volbu napříč rozměry — třeba sever-se-základním nebo jih-s-premium a nic jiného — přidejte položku dvakrát, pokaždé s jednou kombinací, nebo dejte oběma skupinám společný tag, který váš server zahrne do jejich pověření.

Limity

• Až 20 tagů na znalostní položku
• Až 50 tagů v pověření jednoho návštěvníka
• 50 znaků na tag; čárky a svislé čáry nejsou povoleny, protože pověření je řetězec oddělený čárkami

Pozdější změna tagů

Tagy lze u existující položky nahradit, aniž byste ji znovu nahrávali. Změna platí od příští otázky — samotný obsah se znovu nezpracovává.

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

Odesláním prázdného seznamu položku opět zveřejníte. Tagy můžete upravovat i ručně na stránce Access Tags ve své nástěnce.

Co je zaručeno

• Vynucování na straně serveru - filtr běží uvnitř našeho databázového dotazu při vyhledávání; pro neoprávněné návštěvníky otagované položky v kontextu AI vůbec nejsou, takže nemá co uniknout
• Všude fail-closed - žádný podpis, špatný podpis, prošlé pověření, vypnutá funkce, snížený tarif: v každém z těchto případů dostane návštěvník jen veřejný obsah, nikdy víc
• Prohlížeč přístup nezfalšuje - úprava tagů ve vývojářských nástrojích rozbije podpis; klíč má jen váš server
• Vaše logika oprávnění zůstává vaše - nikdy se nedozvíme, jak rozhodujete, kdo dostane který tag; ověřujeme jen, že to váš server potvrdil

Dobré vědět

• Access Tags je autorizace, User Context personalizace - pomocí User Context řekněte AI, kdo člen je; pomocí Access Tags řiďte, z jakých znalostí smí AI čerpat
• Procházený obsah webu je vždy veřejný - pochází z vašeho veřejného webu, takže není co omezovat; tagy platí pro textové, souborové a API položky
• Tagy položky se kombinují pomocí AND - viz Logika tagů výše; každý tag položky musí být obsažen v pověření návštěvníka
• Nový klíč zneplatní všechna stará pověření - udělejte to, pokud klíč mohl uniknout, a poté upravte stránky, aby podepisovaly novým
• Názvy tagů jsou na vás - až 20 na položku, každý 50 znaků, bez čárek a svislých čar; v chatu viditelném návštěvníkům se nikdy neobjeví