Access Tags

概要

すべてのコンテンツが万人向けとは限りません。会員限定の文書、地域限定の資料、有料プラン向けのリソースなどです。Access Tagsを使えば、1つのチャットボットで異なる利用者層に安全に対応できます。ナレッジ項目にタグを付けると、その瞬間からその項目はどの訪問者にも見えなくなります — 例外は、お客様自身のサーバーが署名したそのタグをページで提示する訪問者だけです。制限はAIモデルが関与する前の検索クエリで強制されます。タグを持たない訪問者は、巧妙な質問でもコンテンツを引き出せません。そもそも取得されていないからです。

仕組み

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

有効期限なしの場合はタグ文字列だけに署名します。有効期限ありの場合、期限を過ぎた瞬間にクレームは機能しなくなります — 権限が取り消されうる場合に有用です。訪問者は新しいクレームを得るために、お客様が管理するページを再読み込みする必要があるからです。

タグの論理

項目のタグはANDで結合されます。項目は、そのすべてのタグが訪問者のクレームに含まれている場合にのみ取得されます。訪問者のクレームは必要なだけ権限を持つことができ、照合はそれら全体に対して同時に行われます。

ANDは意図的な設計です。いずれか一致の方式では、項目にタグを追加すると閲覧できる範囲が広がってしまうため、文書を2つのグループに絞ったつもりが、実際には両方に全面公開することになります。すべて一致の方式なら、追加したタグは常にさらに制限する方向にしか働かず、誤りは安全な側に倒れます。

「いずれか」の表し方

その次元を項目に付けないでください。各訪問者のクレームに地域が含まれているなら、地域タグのない文書はすべての地域で利用でき、その他のタグは引き続き適用されます。つまりpremiumだけを付けた項目は「地域を問わず、プレミアム加入者のみ」を意味します。

次元をまたぐ本当の選択が必要な場合 — 例えば北×ベーシック、または南×プレミアムのみ — 項目を組み合わせごとに2回追加するか、両方の対象者に共通のタグを与え、サーバーがそれを双方のクレームに含めるようにしてください。

上限

• ナレッジ項目あたり最大20個のタグ
• 1人の訪問者のクレームに最大50個のタグ
• タグ1つにつき50文字。クレームはカンマ区切りの文字列のため、カンマと縦棒は使用できません

後からタグを変更する

既存の項目のタグは、再アップロードせずに置き換えられます。変更は次の質問から反映され、コンテンツ自体は再処理されません。

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

空のリストを送ると項目は再び公開になります。ダッシュボードのAccess Tagsページで手動編集することもできます。

保証されること

• サーバーサイドの強制 - フィルターは検索時のデータベースクエリの中で動きます。許可のない訪問者にはタグ付き項目がAIのコンテキストにそもそも存在しないため、漏れるものがありません
• あらゆる場面でフェイルクローズ - 署名なし、署名不正、期限切れ、機能オフ、プランのダウングレード。いずれの場合も訪問者は公開コンテンツだけを受け取り、それ以上は決して受け取りません
• ブラウザはアクセスを偽装できない - 開発者ツールでタグを書き換えると署名が壊れます。鍵を持っているのはお客様のサーバーだけです
• 権限のロジックはお客様のもの - 誰にどのタグを与えるかの決め方を当社が知ることはありません。サーバーがそれを表明したことだけを検証します

知っておくと便利

• Access Tagsは認可、User Contextはパーソナライズ - 会員についてAIに伝えるにはUser Contextを、AIが参照できるナレッジを制御するにはAccess Tagsを使ってください
• クロールしたサイトのコンテンツは常に公開 - 公開サイト由来なので制限するものがありません。タグはテキスト・ファイル・API項目に適用されます
• 項目のタグはANDで結合されます - 上記の「タグの論理」を参照してください。項目のすべてのタグが訪問者のクレームに存在する必要があります
• シークレットの再生成で旧クレームはすべて無効に - 漏えいの可能性があれば実行し、その後ページを新しいシークレットで署名するよう更新してください
• タグ名は自由 - 1項目につき最大20個、各50文字まで、カンマと縦棒は不可。訪問者に見えるチャットに表示されることはありません