Access Tags

Преглед

Не всяко съдържание е за всички: документи само за членове, материали за конкретен регион, ресурси от платени нива. С Access Tags един чатбот обслужва различни аудитории безопасно. Слагате таг на елемент от базата знания и от този момент елементът е невидим за всеки посетител — освен за онези, чиято страница представя този таг, подписан от вашия собствен сървър. Ограничението се прилага в нашата заявка за извличане, преди моделът на ИИ изобщо да участва. Посетител без тага не може да измъкне съдържанието с хитри въпроси, защото за него то никога не е било извличано.

Как работи

1. Вие слагате тагове на елементите - на страницата Access Tags или директно през API; елементите без тагове продължават да работят за всички
2. Вашият сървър подписва таговете на всеки посетител - когато влязъл член зареди страницата ви, вашият бекенд определя правата му и ги подписва с таен ключ, който притежавате само вие
3. Уиджетът изпраща подписаното удостоверение - то пътува с всяко съобщение в чата; браузърът само го пренася и не може да го промени, без да счупи подписа
4. Ние проверяваме и филтрираме - валиден подпис отключва елементите със съвпадащи тагове; липсващо, подправено или изтекло удостоверение означава, че посетителят получава само публично съдържание

Настройване

Включете функцията на страницата Access Tags в таблото си — ключ за подписване се генерира автоматично. Пазете го само на своя сървър; всеки, който го има, може да създава валидни удостоверения.

Тагвайте съдържанието на същата страница или при изпращане на елементи през API:

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

След това накарайте сървъра си да изведе подписаното удостоверение до снипета на уиджета. Подписва се списъкът тагове, разделени със запетаи, свързан с вертикална черта с времето на изтичане, когато използвате такова:

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

Същият подпис на Node.js и 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()

Без срок на валидност подписвайте само самия низ с тагове. Със срок удостоверението спира да работи в момента на изтичането му — полезно, когато правата могат да бъдат отнети, защото посетителят трябва да презареди страница под ваш контрол, за да получи ново удостоверение.

Логика на таговете

Таговете на елемент се съчетават с И: елементът се извлича само когато всеки негов таг присъства в удостоверението на посетителя. Удостоверението на посетителя може да носи колкото искате права и съпоставянето става по всички наведнъж.

И е нарочно. При съпоставяне «поне един» добавянето на втори таг към елемент би разширило кой го вижда, така че стесняването на документ до две групи всъщност би го публикувало изцяло и за двете. При съпоставяне «всички» всеки добавен таг може само да стеснява, тъй че грешката пада от безопасната страна.

Изразяване на «който и да е от»

Пропуснете това измерение при елемента. Ако удостоверението на всеки посетител носи региона му, документ без таг за регион е достъпен за всички региони, докато останалите му тагове продължават да важат. Елемент, отбелязан само с premium, значи «всеки регион, само премиум абонати».

За истински избор между измерения — да речем север-с-базов или юг-с-премиум и нищо друго — добавете елемента два пъти, по една комбинация, или дайте на двете аудитории общ таг, който сървърът ви включва в удостоверенията им.

Ограничения

• До 20 тага на елемент от базата знания
• До 50 тага в удостоверението на един посетител
• 50 знака на таг; запетаи и вертикални черти не са позволени, тъй като удостоверението е низ, разделен със запетаи

Промяна на таговете по-късно

Таговете могат да се заменят на съществуващ елемент, без да го качвате отново. Промяната важи от следващия въпрос — самото съдържание не се обработва наново.

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

Изпратете празен списък, за да направите елемента публичен отново. Можете да редактирате таговете и ръчно на страницата Access Tags в таблото си.

Какво е гарантирано

• Прилагане от страна на сървъра - филтърът работи вътре в нашата заявка към базата данни при извличане; за неупълномощени посетители елементите с тагове липсват от контекста на ИИ, така че няма какво да изтече
• Fail-closed навсякъде - без подпис, грешен подпис, изтекло удостоверение, изключена функция, понижен план: във всеки от тези случаи посетителят получава само публично съдържание, никога повече
• Браузърът не може да фалшифицира достъп - редактирането на таговете в инструментите за разработчици чупи подписа; само вашият сървър притежава ключа
• Вашата логика за права остава ваша - никога не научаваме как решавате кой какъв таг получава; проверяваме само, че вашият сървър го е потвърдил

Добре е да знаете

• Access Tags е упълномощаване, User Context е персонализация - използвайте User Context, за да разкажете на ИИ за члена; използвайте Access Tags, за да контролирате от какви знания може да черпи ИИ
• Обходеното съдържание на сайта винаги е публично - то идва от публичния ви сайт, така че няма какво да се ограничава; таговете важат за текстови, файлови и API елементи
• Таговете на елемент се съчетават с И - вижте Логика на таговете по-горе; всеки таг на елемента трябва да присъства в удостоверението на посетителя
• Повторното генериране на ключа прави невалидни всички стари удостоверения - направете го, ако ключът може да е изтекъл, и после обновете страниците си да подписват с новия
• Имената на таговете са ваш избор - до 20 на елемент, по 50 знака, без запетаи и вертикални черти; те никога не се появяват в чата, който посетителите виждат