Access Tags

Prehľad

Nie každý obsah je pre všetkých: dokumenty len pre členov, materiály pre konkrétny región, zdroje platených úrovní. S Access Tags obslúži jediný chatbot rôzne publiká bezpečne. Položke pridáte tag a od tej chvíle je neviditeľná pre každého návštevníka — okrem tých, ktorých stránka tento tag predloží, podpísaný vaším vlastným serverom. Obmedzenie sa vynucuje v našom vyhľadávacom dopyte skôr, než sa model AI vôbec zapojí. Návštevník bez tagu obsah šikovnými otázkami nevytiahne, pretože preň nikdy nebol načítaný.

Ako to funguje

1. Znalostné položky tagujete vy - na stránke Access Tags alebo priamo cez API; položky bez tagov fungujú ďalej pre všetkých
2. Váš server podpisuje tagy každého návštevníka - keď si prihlásený člen načíta vašu stránku, váš back-end určí jeho oprávnenia a podpíše ich tajným kľúčom, ktorý máte len vy
3. Widget odošle podpísané poverenie - putuje s každou správou v chate; prehliadač ho iba prenáša a nemôže ho zmeniť bez toho, aby rozbil podpis
4. My overíme a filtrujeme - platný podpis odomkne položky so zodpovedajúcimi tagmi; chýbajúce, pozmenené alebo expirované poverenie znamená, že návštevník dostane len verejný obsah

Nastavenie

Zapnite funkciu na stránke Access Tags vo svojej nástenke — podpisový kľúč sa vám vygeneruje. Uchovávajte ho len na svojom serveri; ktokoľvek ho má, môže vytvárať platné poverenia.

Obsah otagujte buď na tej istej stránke, alebo pri odosielaní položiek cez API:

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

Potom nechajte svoj server vypísať podpísané poverenie vedľa snippetu widgetu. Podpisuje sa zoznam tagov oddelených čiarkami, spojený zvislou čiarou s časom expirácie, ak ho používate:

<?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 istý podpis v Node.js a Pythone:

// 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 expirácie podpíšte len samotný reťazec tagov. S ním prestane poverenie fungovať v okamihu vypršania — hodí sa, keď možno oprávnenia odobrať, pretože návštevník si musí znova načítať stránku pod vašou kontrolou, aby dostal čerstvé poverenie.

Logika tagov

Tagy položky sa kombinujú pomocou AND: položka je dostupná len vtedy, keď sa každý jej tag nachádza v poverení návštevníka. Poverenie návštevníka môže niesť ľubovoľne veľa oprávnení a porovnáva sa so všetkými naraz.

AND je zámer. Pri porovnaní «aspoň jeden» by druhý tag na položke rozšíril, kto ju smie vidieť, takže zúženie dokumentu na dve skupiny by ho v skutočnosti celý sprístupnilo obom. Pri porovnaní «všetky» môže každý pridaný tag len ďalej obmedzovať, takže chyba padne na bezpečnú stranu.

Vyjadrenie «ktorýkoľvek z»

Vynechajte tento rozmer pri položke. Ak poverenie každého návštevníka nesie jeho región, dokument bez tagu regiónu je dostupný všetkým regiónom, zatiaľ čo jeho ostatné tagy naďalej platia. Položka otagovaná len ako premium teda znamená «akýkoľvek región, iba predplatitelia premium».

Pre skutočnú voľbu naprieč rozmermi — napríklad sever-so-základným alebo juh-s-premium a nič iné — pridajte položku dvakrát, zakaždým s jednou kombináciou, alebo dajte obom skupinám spoločný tag, ktorý váš server zahrnie do ich poverení.

Limity

• Až 20 tagov na znalostnú položku
• Až 50 tagov v poverení jedného návštevníka
• 50 znakov na tag; čiarky a zvislé čiary nie sú povolené, pretože poverenie je reťazec oddelený čiarkami

Neskoršia zmena tagov

Tagy možno pri existujúcej položke nahradiť bez toho, aby ste ju znova nahrávali. Zmena platí od nasledujúcej otázky — samotný obsah sa znova nespracúva.

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

Odoslaním prázdneho zoznamu položku opäť zverejníte. Tagy môžete upravovať aj ručne na stránke Access Tags vo svojej nástenke.

Čo je zaručené

• Vynucovanie na strane servera - filter beží vnútri nášho databázového dopytu pri vyhľadávaní; pre neoprávnených návštevníkov otagované položky v kontexte AI vôbec nie sú, takže nemá čo uniknúť
• Všade fail-closed - žiadny podpis, zlý podpis, expirované poverenie, vypnutá funkcia, znížený plán: v každom z týchto prípadov dostane návštevník len verejný obsah, nikdy viac
• Prehliadač prístup nesfalšuje - úprava tagov vo vývojárskych nástrojoch rozbije podpis; kľúč má len váš server
• Vaša logika oprávnení zostáva vaša - nikdy sa nedozvieme, ako rozhodujete, kto dostane ktorý tag; overujeme len, že to váš server potvrdil

Dobré vedieť

• Access Tags je autorizácia, User Context personalizácia - cez User Context povedzte AI, kto člen je; cez Access Tags riaďte, z akých znalostí smie AI čerpať
• Prechádzaný obsah webu je vždy verejný - pochádza z vášho verejného webu, takže niet čo obmedzovať; tagy platia pre textové, súborové a API položky
• Tagy položky sa kombinujú pomocou AND - pozri Logiku tagov vyššie; každý tag položky musí byť obsiahnutý v poverení návštevníka
• Nový kľúč zneplatní všetky staré poverenia - urobte to, ak kľúč mohol uniknúť, a potom upravte stránky, aby podpisovali novým
• Názvy tagov sú na vás - až 20 na položku, každý 50 znakov, bez čiarok a zvislých čiar; v chate viditeľnom návštevníkom sa nikdy neobjavia