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 символов, без запятых и вертикальных черт; в чате посетителей они никогда не появляются