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

Без терміну дії підписуйте лише сам рядок тегів. З терміном підтвердження перестає працювати в момент його спливу — корисно, коли права можна відкликати: відвідувач мусить перезавантажити сторінку під вашим контролем, щоб отримати свіже підтвердження.

Що гарантується

• Контроль на боці сервера - фільтр працює всередині нашого запиту до бази даних під час пошуку; для неавторизованих відвідувачів елементи з тегами відсутні в контексті ШІ, тож витікати нема чому
• Fail-closed скрізь - немає підпису, неправильний підпис, прострочене підтвердження, вимкнена функція, знижений тариф: у кожному з цих випадків відвідувач отримує лише публічний вміст і ніколи більше
• Браузер не може підробити доступ - редагування тегів в інструментах розробника руйнує підпис; ключ є лише у вашого сервера
• Ваша логіка прав лишається вашою - ми ніколи не дізнаємося, як ви вирішуєте, кому який тег; ми лише перевіряємо, що це підтвердив ваш сервер

Корисно знати

• Access Tags — це авторизація, User Context — персоналізація - використовуйте User Context, щоб розповісти ШІ про члена; використовуйте Access Tags, щоб керувати тим, якими знаннями ШІ може користуватися
• Просканований вміст сайту завжди публічний - він походить із вашого публічного сайту, тож обмежувати нема чого; теги стосуються текстових, файлових та API-елементів
• Відвідувачеві досить одного відповідного тегу - елемент із двома тегами доступний відвідувачеві з будь-яким із них
• Перегенерація ключа робить недійсними всі старі підтвердження - зробіть це, якщо ключ міг витекти, а потім оновіть сторінки, щоб вони підписували новим
• Назви тегів обираєте ви - до 20 на елемент, по 50 символів, без ком і вертикальних рисок; у чаті відвідувачів вони ніколи не з'являються