Access Tags

Pregled

Ni vsa vsebina za vse: dokumenti samo za člane, gradivo za določeno regijo, viri plačljivih ravni. Z Access Tags en sam klepetalni robot varno streže različnim občinstvom. Elementu baze znanja dodate oznako in od tega trenutka je element neviden za vsakega obiskovalca — razen za tiste, katerih stran to oznako predloži, podpisano z vašim lastnim strežnikom. Omejitev se uveljavlja v naši iskalni poizvedbi, še preden se model UI sploh vključi. Obiskovalec brez oznake vsebine ne more izvleči z zvitimi vprašanji, ker zanj nikoli ni bila pridobljena.

Kako deluje

1. Elemente baze znanja označujete vi - na strani Access Tags ali neposredno prek API-ja; elementi brez oznak delujejo naprej za vse
2. Vaš strežnik podpiše oznake vsakega obiskovalca - ko prijavljeni član naloži vašo stran, vaše zaledje določi njegove pravice in jih podpiše s skrivnim ključem, ki ga imate samo vi
3. Gradnik pošlje podpisano potrdilo - potuje z vsakim sporočilom v klepetu; brskalnik ga le prenaša in ga ne more spremeniti, ne da bi pokvaril podpis
4. Mi preverimo in filtriramo - veljaven podpis odklene elemente z ujemajočimi se oznakami; manjkajoče, spremenjeno ali poteklo potrdilo pomeni, da obiskovalec dobi samo javno vsebino

Nastavitev

Vklopite funkcijo na strani Access Tags v nadzorni plošči — podpisni ključ se ustvari samodejno. Hranite ga samo na svojem strežniku; kdorkoli ga ima, lahko ustvarja veljavna potrdila.

Vsebino označite na isti strani ali ob pošiljanju elementov prek API-ja:

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

Nato naj vaš strežnik izpiše podpisano potrdilo poleg odrezka gradnika. Podpiše se seznam oznak, ločenih z vejicami, povezan z navpično črto s časom poteka, kadar ga uporabljate:

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

Isti podpis v Node.js in 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()

Brez časa poteka podpišite samo sam niz oznak. Z njim potrdilo preneha delovati v trenutku poteka — koristno, kadar je pravice mogoče odvzeti, saj mora obiskovalec znova naložiti stran pod vašim nadzorom, da dobi sveže potrdilo.

Logika oznak

Oznake elementa se združujejo z IN: element je pridobljen le, kadar se vsaka njegova oznaka pojavi v potrdilu obiskovalca. Potrdilo obiskovalca lahko nosi poljubno veliko pravic, ujemanje pa poteka po vseh hkrati.

IN je namerno. Pri ujemanju «vsaj ena» bi druga oznaka na elementu razširila, kdo ga sme videti, zato bi zoženje dokumenta na dve skupini v resnici objavilo celoten dokument obema. Pri ujemanju «vse» lahko vsaka dodana oznaka le še bolj omeji, tako da napaka pade na varno stran.

Izražanje «katera koli od»

Izpustite to razsežnost pri elementu. Če potrdilo vsakega obiskovalca nosi njegovo regijo, je dokument brez oznake regije na voljo vsem regijam, medtem ko njegove druge oznake še naprej veljajo. Element, označen samo s premium, torej pomeni «katera koli regija, samo naročniki premium».

Za resnično izbiro med razsežnostmi — recimo sever-z-osnovnim ali jug-s-premium in nič drugega — dodajte element dvakrat, vsakič z eno kombinacijo, ali pa dajte obema občinstvoma skupno oznako, ki jo vaš strežnik vključi v njuni potrdili.

Omejitve

• Do 20 oznak na element baze znanja
• Do 50 oznak v potrdilu enega obiskovalca
• 50 znakov na oznako; vejice in navpične črte niso dovoljene, saj je potrdilo niz, ločen z vejicami

Poznejša sprememba oznak

Oznake je mogoče zamenjati na obstoječem elementu, ne da bi ga znova naložili. Sprememba velja od naslednjega vprašanja — sama vsebina se ne obdela znova.

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

Pošljite prazen seznam, da element spet postane javen. Oznake lahko urejate tudi ročno na strani Access Tags v nadzorni plošči.

Kaj je zajamčeno

• Uveljavljanje na strani strežnika - filter teče znotraj naše poizvedbe v bazo pri iskanju; za nepooblaščene obiskovalce označenih elementov v kontekstu UI sploh ni, zato nima kaj uhajati
• Povsod fail-closed - brez podpisa, napačen podpis, poteklo potrdilo, izklopljena funkcija, znižan paket: v vsakem od teh primerov obiskovalec dobi samo javno vsebino, nikoli več
• Brskalnik ne more ponarediti dostopa - urejanje oznak v razvijalskih orodjih pokvari podpis; ključ ima samo vaš strežnik
• Vaša logika pravic ostaja vaša - nikoli ne izvemo, kako odločate, kdo dobi katero oznako; preverimo le, da je to potrdil vaš strežnik

Dobro je vedeti

• Access Tags je avtorizacija, User Context personalizacija - z User Context povejte UI, kdo je član; z Access Tags nadzorujte, iz katerega znanja sme UI črpati
• Preiskana vsebina spletnega mesta je vedno javna - prihaja z vašega javnega mesta, zato ni česa omejevati; oznake veljajo za besedilne, datotečne in API elemente
• Oznake elementa se združujejo z IN - glejte Logiko oznak zgoraj; vsaka oznaka elementa mora biti v potrdilu obiskovalca
• Ponovno generiranje ključa razveljavi vsa stara potrdila - storite to, če je ključ morda ušel, nato posodobite strani, da podpisujejo z novim
• Imena oznak izberete sami - do 20 na element, vsaka 50 znakov, brez vejic in navpičnih črt; v klepetu, ki ga vidijo obiskovalci, se nikoli ne pojavijo