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