Skip to main content

Pattern 3: Workflow Auth

這個模式是 Direct Connect 的變化形: 前端仍直連 Edge Server, 但在 Workflow 內部加入驗證關卡, 用 HTTP Request Processor 動態呼叫你的 Auth Server。你仍需要有自己的 Auth API, 但不必為了整合而額外建一個後端中繼層。

適用場景​

這個模式適合以下情境:

  • 🔐 已經有外部驗證服務: 你已經有自己的 SSO / OAuth / 內部 Auth Server, 可以驗證 token
  • 🚫 不想為了整合而建一個後端中繼層: 覺得 Backend Relay 太重, 只為驗證而建後端不划算
  • 🆔 需要動態 Auth(per-user 識別)而非固定 API Key: 不能接受 Direct Connect 把固定密鑰放在前端
  • 🧪 驗證邏輯可以表達為「打一支 HTTP API 看結果」: 用 Workflow 的 HTTP Request Processor 即可表達
  • 🎯 想做粗粒度授權(例如「這個使用者能不能用這個 Bot」、「能查哪些資料表」)

如果你還需要保存對話 History、做完整 Audit Log、或實作精細 per-resource 授權, 建議升級到 Backend Relay。

架構圖​

此模式下, 程式碼執行於你的前端(畫面層 + 瀏覽器層)與 Asgard Workflow 內部(Agent 內部層)。你不需要自己的後端服務, 但 Workflow 在執行階段會「向外」呼叫你的 Auth Server。不熟悉執行層的概念? → 架構深入解析

Workflow 內部拓樸​

能力邊界​

✅ 你能做的​

  • 動態 Auth(每則訊息都重新驗證使用者 token)
  • 粗粒度授權(允許/拒絕、決定可用工具集 / 可查資料表 / 可使用功能)
  • 從前端 Payload 把使用者上下文(JWT、user_id、頁面資訊等)送進 Workflow
  • 在 Workflow 內依使用者身份動態切換 Prompt、工具集、模型
  • Bot Provider 本身不必設固定 API Key — 由 Workflow 內的 HTTP 驗證取代

❌ 你不能做的​

做不到的事為什麼
跨裝置同步 History伺服器層 (Server Plane) 不開放, Workflow 無法穩定地持久化資料
完整 Audit Log同上, 稽核需要可信賴的伺服器層攔截事件
精細 per-resource ACLWorkflow 邏輯適合粗粒度判斷, 複雜 ACL 維護成本高
大量 Memory 召回Memory 內容只能透過 Payload 從前端攜帶, 大量資料不適合放前端
隱藏業務邏輯所有業務邏輯(包括 Auth 規則)都集中在 Workflow YAML, 對熟悉 Workflow 的人是可見的

想完整理解這些限制背後的「為什麼」? → 架構深入解析

快速起步​

這個模式分兩個部分:(A) 前端把 JWT 塞入 payload,(B) Workflow 設計驗證關卡。

A. 前端設定: 把 token 帶進 payload​

在你的前端應用裡, 使用 onBeforeSendMessage 把 JWT 塞入 payload:

import { Chatbot } from '@asgard-js/react';
import '@asgard-js/react/style';

export default function App() {
  const userJwt = getUserJwtFromYourAuthSystem(); // 你的 Auth 系統取得

  return (
    <Chatbot
      title="我的 AI 助理"
      config={{
        botProviderEndpoint: 'https://api.asgard-ai.com/ns/your-namespace/bot-provider/your-bot',
        // 注意:這個模式下 Bot Provider 可以不設 API Key(無 Auth)
        //       因為驗證會發生在 Workflow 內部
      }}
      customChannelId={channelId}
      onBeforeSendMessage={(params) => ({
        ...params,
        payload: {
          ...params.payload,
          jwt: userJwt,  // ← 關鍵:JWT 塞入 payload
        },
      })}
    />
  );
}

B. Workflow 設計: 加上驗證關卡​

在 Odin Studio 編輯 Workflow, 在 LLM Completion Processor 之前 插入兩個 Processor:

  1. HTTP Request Processor — 用 prevPayload.jwt 打你的 Auth API
  2. Router Processor — 根據 HTTP 回應決定路由

HTTP Request Processor 設定​

欄位值
url你的 Auth API URL(例如 https://auth.your-company.com/verify)
methodPOST
parseJsontrue
Authorization(Header)`Bearer ${prevPayload.jwt}`

執行後, 回應會放在 httpResponse.json.*(例如 httpResponse.json.allowed_scopes)。

把 HTTP 結果存進 Context​

接著用 Update Context Processor 把結果保存, 後續 Processor 才能讀。需設定兩個欄位:

欄位值
變數名稱(Name)allowed_scopes
表達式(Expression)見下方
(() => {
  return httpResponse.json.allowed_scopes || [];
})()

allowed_scopes 在後續有兩個用途:

  1. Router 判斷: 陣列非空則放行
  2. Contains filtering: 傳入 LLM Processor, 限縮 LLM 實際可存取的資源範圍(例如可查的資料表、可用的工具集)

Router Processor 設定​

// Case 1: 驗證通過(allowed_scopes 非空)
(() => {
  return allowed_scopes.length > 0;
})()
  • case-1 → 連到主流程的 LLM Completion Processor
  • else → 連到一個 Push Message Processor, 顯示「您沒有權限」並回到 Listen Message

一個完整流程的範例​

以「資料分析 Bot」場景為例:

整個流程 沒有你自建的後端服務, 所有驗證與授權邏輯都被 Workflow 表達。

限制與注意事項​

  1. 所有業務邏輯集中在 Workflow: 當驗證規則變複雜, Workflow YAML 會難以維護。設計時要在「Workflow 邏輯複雜度」與「自建後端的成本」之間取得平衡; 邏輯太重時應升級到 Backend Relay。

  2. History 不適合用 Workflow Auth 持久化: Workflow 沒有可靠的持久化資料儲存層。如果需要保存對話歷史, 選項是:

  3. Memory 暴露問題: 從前端攜帶 Memory 進 Payload, 內容對使用者可見且可竄改。敏感的個人化資料應放在伺服器層 — 即 Backend Relay。

  4. HTTP Request Processor 是「同步」呼叫: 每則訊息都要等你的 Auth API 回應才能繼續。Auth API 慢 = AI 回應慢。建議 Auth API 在 50ms 內回應, 並做好快取。

  5. 無 Server-side Audit Log: Workflow 的 Log 受限於 Asgard 平台, 且使用者前端行為(例如 Retry、Cancel)不會反映到 Workflow Log 中, 不能當作完整稽核紀錄。

延伸閱讀​