AIP-TALK 集成文档
下载示例代码 开始配置
指南目录

变更说明(2026-11):本产品历史上曾使用 CowAgent 作为产品内部代号,现对外已统一为 SebAgent,本文已全部改用新名称。为保证与示例工程代码及运行报错逐字一致,以下历史标识保留原名:环境变量 COWAGENT_BASE_URL、前端配置项 cowagentBaseUrl、iframe 事件 cow:ready,以及报错文案 “Cannot connect to CowAgent server”。

Third-party integration · Client guide

AIP-TALK
客户端开发指南

从后台下发的接入参数开始,完成第三方用户单点登录、JIT 自动开通和 AIP-TALK 对话框嵌入。本文与当前示例工程的配置和调用链保持一致。

HS256 JWT 单点登录 用户与租户自动开通 iframe 开箱嵌入

一次页面加载,完成整个登录链路

识别第三方用户身份
服务端签名并换取 Token
挂载已登录的 AIP-TALK
客户端页面localhost:6001
集成后端代理127.0.0.1:6002
Assertion 有效期60 seconds
令牌注入方式iframe ?token=
01

接入总览

先理解浏览器、集成后端和 SebAgent 各自负责什么。

本工程是一个独立的第三方门户示例。前端负责读取配置和挂载 iframe;Flask 后端保管 issuer secret、签发 assertion 并换取 Token;SebAgent 负责校验身份、JIT 开通以及签发 v2 Token。

系统架构与令牌流向Browser → Proxy → SebAgent
AIP-TALK 第三方接入架构图 第三方浏览器调用集成后端获取 Token,集成后端使用签名 assertion 调用 SebAgent,最后浏览器通过带 Token 的 iframe 加载 AIP-TALK。 IDENTITY & TOKEN FLOW 第三方浏览器 Flask 集成代理 SebAgent / AIP-TALK Vite + TypeScript · :6001 src/config.ts 读取配置 · 挂载 iframe Python + Flask · :6002 .env + server/sso.py 保管 Secret · 签发 assertion SSO 身份提供方 校验 · JIT · 用户映射 签发 SebAgent v2 Token ① 请求登录 Token ③ HS256 assertion ④ v2 Token ② Token + 用户身份 ⑤ /embed/aip-talk?token=... Secret 不进入浏览器;浏览器只持有交换后的 v2 Token。

本工程使用“后端对后端换 Token + iframe 嵌入”,不使用浏览器表单 POST /auth/sso 的 Cookie 登录方式。

02

准备工作

先拿到后台生成或确认的接入信息,再修改本地配置。

A
Issuer 接入凭证

后台生成 ISSUER_ID 和 ISSUER_SECRET,用于标识第三方系统并签名 assertion。

B
SebAgent 服务地址

确认第三方后端实际可达的地址。该地址同时用于 JWT 的 aud,必须与后台 audience 配置匹配。

C
前端 Origin 已登记

将浏览器访问地址的协议、主机和端口完整加入 issuer 的 allowed_origins,不能使用通配符。

D
本地开发环境

Python 3.10+、Node.js 20+、npm 10+,并确保 6001、6002 端口以及 SebAgent 服务可用。

配置一致性是接入成功的关键:COWAGENT_BASE_URL 要同时满足“后端能访问”和“与后台受众匹配”;FRONTEND_ORIGIN 要与浏览器地址栏中的 Origin 完全一致。

03

配置环境变量 .env

这些变量由集成后端读取,issuer secret 永远不会下发到前端。

首次配置可复制 .env.example 为 .env,再按下表填写。后台生成或提供的值请直接替换,不要在文档、聊天或代码仓库中传播真实 secret。

环境变量来源作用与配置要求示例 / 默认值
COWAGENT_BASE_URL后台提供SebAgent 根地址。后端调用 SSO 接口,并将其作为 assertion 的 aud;必须匹配后台的 audience 或 additional_audiences。https://sebagent.example.com
ISSUER_ID后台生成第三方 issuer 唯一标识,对应 SebAgent 的 sso_trusted_issuers 配置,并写入 JWT 的 iss。yunshu-os
ISSUER_SECRET后台生成 · 保密HS256 签名密钥。只保存在集成后端,不得写入 TypeScript、HTML、URL 或日志。replace-with-issued-secret
APP_HOST本地部署Flask 集成代理监听地址。本机联调保持回环地址;需要对外提供服务时再按部署方案调整。127.0.0.1
APP_PORT本地部署Flask 集成代理监听端口。Vite 的 /api 请求默认代理到此端口。6002
FRONTEND_ORIGIN本地配置 + 后台登记允许调用代理接口的前端 Origin,同时控制 Flask CORS。必须精确包含协议、主机和端口。http://localhost:6001
COWAGENT_BASE_URL=https://sebagent.example.com
ISSUER_ID=yunshu-os
ISSUER_SECRET=replace-with-issued-secret

APP_HOST=127.0.0.1
APP_PORT=6002
FRONTEND_ORIGIN=http://localhost:6001

不要提交真实 .env。如果 secret 曾经进入前端产物、Git 历史或公开日志,应立即在后台轮换,而不是只删除本地文件。

04

配置前端 src/config.ts

页面标题、品牌、用户身份、租户和对话框外观集中在这里。

页面没有登录表单,加载时会按照 appConfig 自动换取 Token 并挂载 AIP-TALK。修改后 Vite 会热更新。

配置项类型当前工程示例说明
pageTitlestring云数工业 · AIP-TALK浏览器标签页标题。
logoUrlstring/yunshu-logo.png标题栏 Logo。public/ 下的文件以 / 开头引用。
logoAltstring云数工业 YUNSHU INDUSTRYLogo 替代文本,用于无障碍和图片加载失败场景。
cowagentBaseUrlstring空字符串建议留空,前端通过 /api/config 使用后端 .env 中的地址;填写后会覆盖后端默认值。
userIdstringyunshu第三方外部用户 ID,进入 JWT 的 sub。生产环境应使用稳定且唯一的工号或用户 ID;留空时后端生成带时间戳的 demo 用户。
tenantIdstringtnt_81598fe488b508ba第三方外部租户 ID,进入 JWT 的 tid;留空时后端使用 demo-tenant。
displayNamestringyunshuAIP-TALK 用户显示名,进入 JWT 的 name;留空时使用用户 ID。
theme'light' | 'dark'light对话框初始主题,iframe ready 后同步。
langstringzh对话框初始语言,可选 zh 或 en。
export const appConfig: AppConfig = {
  pageTitle: '云数工业 · AIP-TALK',
  logoUrl: '/yunshu-logo.png',
  logoAlt: '云数工业 YUNSHU INDUSTRY',

  // 推荐留空,统一使用后端 .env 中的 COWAGENT_BASE_URL
  cowagentBaseUrl: '',

  // 示例身份;正式系统应替换为当前登录用户
  userId: 'yunshu',
  tenantId: 'tnt_81598fe488b508ba',
  displayName: 'yunshu',

  theme: 'light',
  lang: 'zh',
};

E2E 临时覆盖:可使用 ?server=、?user=、?tenant=、?name= 覆盖对应配置。它们用于测试,不应作为生产环境传递用户身份的机制。

05

第三方用户如何登录

用户不需要再次输入密码;第三方身份通过签名 assertion 传递给 SebAgent。

单点登录完整时序SSO assertion → JIT → v2 Token → iframe
第三方用户登录 AIP-TALK 时序图 用户打开第三方页面,浏览器请求集成后端,后端签名 assertion 并调用 SebAgent。SebAgent 校验、自动开通用户并返回 Token,浏览器最后加载带 Token 的 AIP-TALK iframe。 第三方用户 浏览器 / 前端 Flask 集成后端 SebAgent 1 打开第三方门户 2 POST /api/auth/token 示例读取 config.ts;生产从已验证登录态识别用户 3 生成 60 秒 HS256 assertion iss / sub / tid / name / roles / jti 4 POST /api/v1/sso/token 5 校验签名、aud、exp、jti 用户映射 + JIT 自动开通 6 返回 v2 Token + 内部身份 7 返回安全响应字段 8 /embed/aip-talk?token=... 9 cow:ready · 登录完成

移动端可横向滚动查看时序图。每一步的文字说明如下。

当前示例工程

没有账号密码登录。页面启动后直接使用 config.ts 中的 userId、tenantId 和 displayName 自动完成 SSO。

正式第三方系统

应先完成你们自己的登录认证,再由服务端从 Session 或身份上下文中取得用户、租户和角色,不能信任浏览器自行声明。

用户身份在链路中如何变化

前端传入的是“外部身份”,SebAgent 返回的是“内部身份”。同一个稳定的 userId 会映射到同一个内部用户;留空则可能每次创建新的 demo 用户。

第三方身份userId / tenantIddisplayName 作为用户姓名
签名 assertionsub / tid / name外加 iss、aud、exp、jti、roles
SebAgent 内部身份usr_… / ext:…user_mapping → JIT → v2 Token

集成后端实际执行的操作

1
接收前端请求并确定用户身份

server/app.py 接收 user_id、tenant_id、name 等字段并校验 ID 格式。

2
生成一次性 JWT assertion

server/sso.py 写入 iss、sub、tid、aud、iat、exp、jti、name、email 和 roles,再使用 ISSUER_SECRET 做 HMAC-SHA256 签名。

3
向 SebAgent 交换 v2 Token

后端请求 POST {COWAGENT_BASE_URL}/api/v1/sso/token,JSON 请求体为 {"assertion": "..."}。

4
将 Token 注入 AIP-TALK

前端拿到 Token 后创建 /embed/aip-talk?token=... iframe;收到 cow:ready 后同步主题和语言,页面状态变为“已就绪”。

角色注意事项:当前示例在 roles 缺省时使用 system:admin,仅用于联调。并且 SebAgent 只在首次 JIT 创建用户时应用角色;复用同一外部用户 ID 时,修改配置不一定会改变已有角色。

06

多用户映射(user_mapping)

第三方系统有多个用户时,把每个外部用户固定绑定到 SebAgent 内部用户,不再依赖 JIT 现场创建。

上一节的 JIT 自动开通适合快速联调:未命中的外部用户会被现场创建为 ext:<issuer>:<sub> 形式的账号。当第三方系统要求“谁是谁”完全受控——例如 hkgc001 发行方下的 test001-hkgc、hkgc 等账号必须各自对应租户里的真实成员——应改用显式 user_mapping。整个配置由三方协作完成:

1
租户管理员创建内部用户

企业AI大脑(SebAgent)租户管理员在「系统管理 > 用户管理」中为本租户逐个创建用户(或复用现有用户)。用户列表的“用户ID”列即为 usr_ 前缀的内部用户 ID,复制备用。

2
第三方整理映射 JSON

第三方系统把「外部用户 ID(JWT 中的 sub,对应示例工程 config.ts 的 userId)→ 内部用户 ID」整理成一个 JSON 对象,交给 SebAgent 系统管理员。

3
系统管理员写入发行方配置

admin 打开「系统管理 > 第三方集成设置」,在发行方列表中选中对应发行方(如 hkgc001),将 JSON 粘贴进 user_mapping(JSON 对象) 输入框,点击「保存映射」。保存即时生效,无需重启服务。

{
  "test001-hkgc": "usr_ede5e7366f202571",
  "test002-hkgc": "usr_c4ff9c0a65b293e8",
  "hkgc": "usr_641667aab88987d0",
  "hkgc-r": "usr_d00ffd02fab4fb9c"
}
后台配置入口系统管理 > 第三方集成设置 > hkgc001
第三方集成设置页面截图:发行方 hkgc001 的 user_mapping(JSON 对象)输入框中已填入四条映射,红框标注该输入区域,下方为「保存映射」按钮

红框处粘贴第三方提供的映射 JSON 并点击「保存映射」;同一面板还可维护 tenant_mapping 与开通策略。

命中与回退规则

键与值的含义

键 = 断言中的 sub(第三方传入的 userId);值 = 内部 usr_ 用户 ID。被映射用户必须属于 tenant_mapping 解析后的目标租户,否则视为未命中并继续后续解析。

显式映射优先级最高

user_mapping 命中优先于 SSO metadata 隐式链接和 JIT 自动创建;事后补配或修改的映射在下一次 Token 交换时生效。

严格模式

关闭「自动创建未映射用户(JIT)」后,仅 user_mapping 命中或历史已开通的用户可登录,其余一律拒绝——生产环境推荐关闭。

JSON 格式校验

保存时前端会校验必须是 JSON 对象且所有值为字符串;格式错误会直接提示,不会写入。

映射变更的影响范围:「保存映射」只影响之后的 Token 交换;已签发且未过期的 v2 Token 仍携带旧身份,等待其自然过期或重新登录即可切换到新映射。

07

数据权限:角色同步与行级数据权限

第三方系统在断言里声明用户角色与数据属性,SebAgent 管理员一次性配置映射与绑定,权限随登录自动生效、随第三方变更自动同步。

上一节的 user_mapping 解决“谁是谁”;本节解决“谁能看哪些数据”。整条链路为 Claims → Attributes → Bindings → Filters:断言声明(Claims)经映射落成用户属性(Attributes),管理员把属性绑定到表的过滤列(Bindings),查询时由执行层自动注入行级过滤(Filters)。

数据权限链路Claims → Attributes → Bindings → Filters
数据权限链路图 第三方断言携带 roles 与 attrs;登录交换时映射为用户角色与属性;管理员配置行过滤绑定;查询时按属性值注入参数化 WHERE 过滤。 DATA PERMISSION PIPELINE ① 断言声明 roles: ["ws_operator"] attrs: { workshops: [...] } 第三方开发签名时写入 ② 登录同步 role_mapping → 内部角色 attribute_mapping → 属性 每次交换 Token 时覆盖同步 ③ 行过滤绑定 prod.workshop_id ← 用户属性 workshops 租户管理员配置一次 ④ 查询过滤 WHERE workshop_id IN (?, ?) 参数化注入 绑定关系是静态的(管理员配置一次);属性值是动态的(每次登录由断言刷新)——同步因此自然发生,无需手工对账。

三方分工:第三方开发负责断言带 roles/attrs;SebAgent 管理员负责映射与绑定;最终用户无感。

参数定义速查(配置前先认清每个字段)

三张表覆盖本链路的全部参数:断言里第三方要传的、发行方卡片里管理员要配的、行过滤策略里绑定要写的。所有字段名区分大小写。

断言字段(JWT payload)类型必填说明与传递方式示例
issstring必填发行方 ID,必须与 SebAgent 后台配置的 issuer_id 逐字一致;dry-run 端点也从这里解析发行方。"yunshu-os"
substring必填外部用户唯一 ID,长期稳定不变;用于 user_mapping 命中或 JIT 建号。不要用显示名。"zhangsan"
tidstring必填外部组织/租户 ID;用于 tenant_mapping 命中或自动建租户。"acme"
audstring必填接收方基础 URL;必须命中发行方配置的 audience 或 additional_audiences 之一。"http://111.9.54.6:9899"
iat / expint(Unix 秒)必填签发时间 / 过期时间;TTL(exp-iat)≤ 60 秒,双方时钟需同步。1761200000 / 1761200060
jtistring必填断言唯一编号,防重放;每次签名随机生成,不缓存复用。"9f2c...hex"
name / emailstring建议显示名与邮箱;开启「同步属性」时更新用户资料。"张三" / "zs@acme.com"
rolesstring[]可选外部角色名(不是 SebAgent 内部角色 ID),经 role_mapping 翻译;未映射的被忽略。发行方未开 sync_roles 时,仅在 JIT 首次建号时作为角色来源。["ws_operator"]
attrsobject<string, string[]>可选用户数据属性——行级权限的取值来源。键须出现在 attribute_mapping 左键中才会进入身份层;值统一为字符串数组(标量会被规范化为单元素数组,null 视为空数组)。{"workshops": ["一车间", "二车间"]}
发行方「权限同步」字段类型缺省说明示例
sync_rolesbool关闭开启后,断言 roles 经 role_mapping 翻译后每次登录覆盖式同步:新增的补授、消失的回收(只回收同步来源角色,手工授予不受影响)。开启
role_mappingJSON 对象空外部角色名 → 内部角色 ID。目标角色必须真实存在,否则按未映射处理(不产生幻影授权)。开启 sync_roles 时至少配置一条。{"ws_operator": "tenant:user"}
sync_user_attrsbool关闭开启后,断言 attrs 经 attribute_mapping 翻译写入用户数据属性;上次同步但这次未声明的键被移除,手工配置的同名键不受影响。开启
attribute_mappingJSON 对象空断言 attrs 键 → 内部属性键(可改名归一)。只有左键列出的键会进入身份层——这是防止手机号等敏感属性被意外引入的边界。{"workshops": "workshops"}
行过滤规则字段取值说明示例
column物理列名过滤列;必须是表 schema 中真实存在的列(幻影列直接拒绝,防注入)。workshop_id
op见下方操作符表比较操作符,白名单枚举,不接受任意 SQL 片段。in
value_sourceuser_attr / literal值来源:user_attr = 取当前用户的数据属性(主用,随登录动态刷新);literal = 固定值(兜底,无第三方集成的小场景)。user_attr
attr_key属性键名value_source=user_attr 时引用;用户缺该属性 = 明确拒答(fail-closed),而不是静默返回空表。workshops
valuestring[]value_source=literal 时的固定值列表;属性值/固定值一律以 ? 参数化传递,永不拼进 SQL 文本。["一车间"]
操作符 op含义值个数典型用法
eq= 等于1单列单值:region = 用户属性 region
neq≠ 不等于1排除特定值
in包含于≥1最常用:workshop_id IN (用户的车间列表)
not_in不包含于≥1黑名单式排除
gt / ge> / ≥1数值/时间下界,如 level <= 用户密级 的反向
lt / le< / ≤1数值/时间上界
between区间2闭区间过滤,如日期区间
多规则 = AND 收窄

同一张表配多条规则时按交集生效(fail-closed 方向);同表多策略命中同样取交集,不会互相放宽。

谁能绕过

超级管理员与租户管理员天然直通(便于排障);策略可另配豁免角色/用户名单。普通用户无任何绕过路径,缓存也按参数指纹隔离——不同属性值的用户互不可见对方结果。

属性值的两个来源

①SSO 同步:断言 attrs 经 attribute_mapping 落入(随登录自动刷新);②手工维护:租户管理员在「系统管理 > 用户管理」编辑用户的「数据属性」。两者可混用,手工值不被 SSO 回收(同名键以同步为准)。

一、配置角色与属性同步(发行方「权限同步」区)

1
打开发行方配置

admin 进入「系统管理 > 第三方集成设置」,在发行方列表选中目标发行方(如 yunshu-os),展开「权限同步」区。

2
开启角色同步并配置映射

勾选「同步角色(sync_roles)」,在 role_mapping 中把外部角色名映射到内部角色 ID。未映射的外部角色会被忽略(不报错),映射到不存在的内部角色同样按未映射处理,不会产生幻影授权。

3
开启属性同步并配置映射

勾选「同步用户属性(sync_user_attrs)」,在 attribute_mapping 中把断言 attrs 的键映射为内部属性键(可改名归一,如第三方叫 workshops、内部统一叫 workshops)。只有出现在映射左键里的属性才会进入身份层,断言里多带的其他键被丢弃——这是防止敏感属性被意外引入的边界。

4
保存并验证

保存即时生效,无需重启。用下文「三级探针」的 L1 交换探针确认响应 synced 回执内容符合预期。

// role_mapping(JSON 对象:外部角色名 → 内部角色 ID)
{
  "ws_admin": "tenant:viewer",
  "ws_operator": "tenant:user"
}

// attribute_mapping(JSON 对象:断言 attrs 键 → 内部属性键)
{
  "workshops": "workshops",
  "depts": "departments"
}
覆盖式同步,只回收“同步来的”

SebAgent 记录每个用户上次由 SSO 写入的角色集合(sso_synced_roles)。下次登录:断言里新增的角色补授、消失的角色回收;管理员手工授予的角色不在回收范围。属性同理(sso_synced_attr_keys):上次同步但这次未声明的键被移除,手工配置的同名键不受影响。

时序示例

张三首次登录断言 roles: ["ws_admin"] → 获得映射后的内部角色;管理员另手工授予「数据管理员」。一周后第三方把张三调整为 roles: ["ws_operator"] 并重新登录 → ws_admin 映射角色被回收、ws_operator 映射角色生效,手工授予的「数据管理员」原样保留。

同步失败不阻断登录

同步过程异常时用户仍可正常登录,失败原因记入审计(sso.sync.failed)并在响应 synced.error 留痕;成功时记 sso.sync.applied。第三方可用 L1 探针回执发现异常。

不开关 = 零变化

两个开关默认关闭。存量发行方不配置时行为与此前完全一致:角色仅在 JIT 首次建号时应用一次,断言 attrs 键被忽略,交换响应回执显式返回 "synced": {"disabled": true}。

二、配置行级数据权限(端到端车间示例)

场景:生产记录表 prod_records 有物理列 workshop_id;要求用户只能看到自己授权车间的行。授权清单由第三方系统在断言 attrs.workshops 中声明。

1
第三方断言带属性

按上一节开启 sync_user_attrs 并配置 attribute_mapping;第三方后端签名时写入 attrs: {"workshops": ["一车间", "二车间"]}(值统一为字符串数组)。

2
管理员配置绑定(一次)

租户管理员打开「数据查询 > Schema > 行级权限」TAB,选中数据源后新建策略:表 prod_records → 添加规则:列 workshop_id(列名下拉,含数据字典业务名)→ 操作符 in → 值来源「用户属性」→ 属性键 workshops。也可用预设模板「按车间」一键生成同构规则,或用「探查真实值」对该列做 SELECT DISTINCT 后点选,杜绝手输错别字。

3
生效验证

用户 A(workshops=["一车间"])问“各车间本月产量”→ 结果只含一车间,查询被自动改写为 WHERE workshop_id IN (?) 并参数化传值;用户 B 未配置该属性 → 收到明确拒答(见下方文案),而不是静默看到空表。

4
权限试算

「行级权限」TAB 的策略卡片上点「试算」:选择目标用户 → 展示最终生效的 WHERE 片段、参数、表总行数与该用户可见行数,以及该用户当前属性值——上线前即可确认真相,不必等用户反馈。

缺属性 = 明确拒答(fail-closed)。用户缺少绑定所需的属性时,AI 原样转述:
“该查询涉及按数据范围管控的数据表,需要为您的账号配置数据属性(workshops)后才能查询;请联系管理员处理。”
拒答文案不泄露 SQL、列名与属性值。管理员(system:admin / tenant:admin)天然直通;策略可配置豁免角色/用户;同表多条规则按 AND 收窄。

三、第三方开发:断言怎么写

只需在现有签名代码上多传一个 attrs 参数(示例工程 server/sso.py 已内置该参数)。三种语言等价写法:

from sso import make_assertion

assertion = make_assertion(
    issuer_id="yunshu-os",
    issuer_secret=ISSUER_SECRET,
    audience="http://111.9.54.6:9899",
    external_user_id="zhangsan",
    external_tenant_id="acme",
    name="张三",
    roles=["ws_operator"],                    # 外部角色名,经 role_mapping 翻译
    attrs={"workshops": ["一车间", "二车间"]},  # 数据属性,经 attribute_mapping 翻译
)
const jwt = require("jsonwebtoken");

const attrs = { workshops: user.workshops };  // 从第三方自己的权限表查出
const assertion = jwt.sign(
  {
    iss: ISSUER_ID,
    sub: user.id,
    tid: user.orgId,
    aud: COWAGENT_BASE_URL,
    name: user.name,
    email: user.email,
    roles: user.cowRoles,
    attrs: attrs,                             // 如 { workshops: ['一车间', '二车间'] }
  },
  ISSUER_SECRET,
  { algorithm: "HS256", expiresIn: 60 }
);
// 注意:jsonwebtoken 生成的标准 JWT 与 SebAgent 的 unpadded base64url
// 签名输入兼容;自实现签名时不要对 header.payload 加 '=' padding。
Map<String, Object> attrs = new HashMap<>();
attrs.put("workshops", Arrays.asList("一车间", "二车间"));

String assertion = JWT.create()
    .withIssuer("yunshu-os")
    .withSubject("zhangsan")
    .withAudience("http://111.9.54.6:9899")
    .withClaim("tid", "acme")
    .withClaim("name", "张三")
    .withClaim("email", "zhangsan@example.com")
    .withClaim("roles", Arrays.asList("ws_operator"))
    .withClaim("attrs", attrs)
    .withClaim("jti", UUID.randomUUID().toString().replace("-", ""))
    .withIssuedAt(new Date())
    .withExpiresAt(new Date(System.currentTimeMillis() + 60_000))
    .sign(Algorithm.HMAC256(ISSUER_SECRET));
键名与类型约定

attrs 的值统一为字符串数组;标量会被规范化为单元素数组,null 视为空数组。键名必须与 attribute_mapping 的左键一致(区分大小写)。roles 填外部角色名,未映射的被忽略(不报错)。

其余约束与登录断言完全相同

aud 必须命中发行方配置的 audience 或 additional_audiences;TTL ≤ 60 秒;每次签名生成新 jti(防重放)。

四、三级探针:30 秒确认真相

L0
本地自检(不触网)

用示例工程 peek_issuer_id() 或 jwt.io 解开 payload,确认 attrs 键名、aud、exp 正确。

L1
交换探针(落地真相)

用断言换 Token,响应里的 synced 回执就是角色与属性映射的落地明细。

L2
生效验证

拿 Token 问一句越界问题(如“三车间本月产量”),期望结果被过滤或明确拒答;管理员侧审计可见 sso.sync.applied / table.row_filter.denied。

ASSERTION=$(python -c "from sso import make_assertion; print(make_assertion(
  'yunshu-os', 'ISSUER_SECRET', 'http://111.9.54.6:9899',
  'zhangsan', 'acme', name='张三',
  roles=['ws_operator'], attrs={'workshops': ['一车间']}))")

curl -s -X POST "http://111.9.54.6:9899/api/v1/sso/token" \
  -H 'Content-Type: application/json' -d "{\"assertion\": \"$ASSERTION\"}"
{
  "status": "success",
  "token": "v2....",
  "user_id": "usr_ede5e7366f202571",
  "tenant_id": "tnt_1f3a9c2e7b5d48a0",
  "roles": ["tenant:user"],
  "expires_in": 2592000,   // 跟随服务端 web_session_expire_days 配置(默认 30 天 × 86400 秒)
  "synced": {
    "roles": {
      "applied": ["tenant:user"],   // 本次映射命中的内部角色
      "revoked": [],                // 本次回收的上次同步角色
      "unmapped": []                // 断言里未被映射忽略的外部角色
    },
    "attrs": { "workshops": ["一车间"] },  // 实际落入身份层的属性
    "attrs_unmapped": []                   // 未在 attribute_mapping 中而被丢弃的键
  }
}
// 未开启同步开关时回执为:"synced": {"disabled": true}
// —— 显式标注,避免“以为同步了其实没开”。

五、dry-run 校验端点(上线前自助排障)

POST /api/v1/sso/assertion/verify 只验签 + 解析映射 + 返回预览,不建号、不发 Token、不消费 jti、不写身份层——签错、配错在上线前即可发现。该端点无需登录态:断言签名本身就是凭证;发行方由断言 iss 声明自动解析,无需在请求体中另传。

curl -s -X POST "http://111.9.54.6:9899/api/v1/sso/assertion/verify" \
  -H 'Content-Type: application/json' -d "{\"assertion\": \"$ASSERTION\"}"
{
  "status": "success",
  "valid": true,
  "issuer": "yunshu-os",
  "claims": { "sub": "zhangsan", "tid": "acme", "name": "张三",
              "roles": ["ws_operator"], "attrs": {"workshops": ["一车间"]}, ... },
  "tenant": { "external_tid": "acme", "mode": "linked", "tenant_id": "tnt_1f3a9c2e7b5d48a0" },
  "user":   { "external_sub": "zhangsan", "mode": "mapped", "user_id": "usr_ede5..." },
  "sync_preview": {
    "disabled": false,
    "roles": { "would_apply": ["tenant:user"], "unmapped": [] },
    "attrs": { "workshops": ["一车间"] }
  }
}
// tenant/user 的 mode 取值:mapped(显式映射)/ linked(历史链接)/
// would_create(将 JIT 创建)/ blocked(严格模式将被拒绝)/
// mapped_missing(映射目标已不存在)/ missing_sub(断言缺 sub)。

排障顺序:先 L0 再 L1 再 L2。签名与结构问题在 L0 就能发现;映射与开关问题看 L1 的 synced 回执或 dry-run 的 sync_preview;过滤语义问题用管理员侧「权限试算」面板看最终 WHERE 与命中行数。全程不需要翻 SebAgent 源码。

08

启动与验证

分别启动集成后端和 Vite 前端,然后检查自动登录结果。

1
安装 Python 与 Node.js 依赖

在工程根目录执行以下命令。

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
npm install
source venv/bin/activate
python server/app.py
npm run dev

打开 http://localhost:6001。页面会自动完成 Token 交换并挂载对话框,无需手工输入用户。

验证成功的标准:右上角状态显示“已就绪”,AIP-TALK iframe 可见,且对话框中的用户、租户和权限符合本次配置。后端健康检查可访问 http://127.0.0.1:6002/api/health。

前端换 Token 接口(由工程自动调用)

POST/api/auth/tokenContent-Type: application/json
{
  "user_id": "yunshu",
  "tenant_id": "tnt_81598fe488b508ba",
  "name": "yunshu",
  "email": "yunshu@example.com"
}
{
  "status": "success",
  "token": "<sebagent-v2-token>",
  "user_id": "usr_...",
  "tenant_id": "ext:yunshu-os:tnt_...",
  "roles": ["tenant:user"],
  "expires_in": 2592000   // 与 L1 回执同源:跟随服务端会话配置
}

客户端通常不需要手工调用该接口,src/embed.ts 已封装调用和 iframe 创建。虽然提供了 refreshToken() 方法,当前示例没有根据 expires_in 自动调度刷新;重新加载页面会重新执行交换。Token 有效期 expires_in 跟随服务端 web_session_expire_days 配置(默认 30 天)。

09

常见故障排查

优先检查地址、Origin、受众和身份配置是否一致。

现象常见原因处理方法
Cannot connect to CowAgentSebAgent 未启动、网络不可达或地址端口错误。从运行集成代理的机器验证 COWAGENT_BASE_URL 可达,不要只在个人浏览器上测试。
iframe 403 / Origin not allowed前端 Origin 未加入 issuer 的 allowed_origins,或协议、主机、端口不一致。以浏览器地址栏为准修正 FRONTEND_ORIGIN,并同步后台 allowed_origins。
Assertion audience 校验失败COWAGENT_BASE_URL 与后台 audience / additional_audiences 不匹配。统一实际服务地址与后台受众配置,注意 localhost、局域网 IP 和域名不是同一个 aud。
前端无法调用 /api/auth/token6002 后端未启动,或 Vite 代理未生效。先访问 /api/health;确认 APP_PORT=6002,并重启两个开发服务。
Assertion 过期或重放服务器时间偏差,或同一个 assertion 被重复提交。校准服务器时间。每次登录由 make_assertion() 生成新的 jti,不要缓存并复用 assertion。
每次登录都创建新用户userId 留空,后端自动生成了带时间戳的用户 ID。为每个真实用户配置稳定、唯一且长期不变的外部用户 ID。
修改 roles 后权限没有变化用户已经通过 JIT 创建,角色只在首次创建时应用。按 SebAgent 管理流程调整已有用户权限;联调时可使用新的测试用户 ID 验证首次开通。
Assertion signature 校验失败issuer secret 不匹配,或自实现签名时对带 = padding 的串签名。对 unpadded 的 header.payload 计算 HMAC-SHA256;优先复用示例工程 sso.py。
Assertion audience 校验失败(权限同步场景)断言 aud 不是发行方配置的可达地址。在发行方 additional_audiences 中补上该地址(域名、局域网 IP、localhost 互不相同)。
严格模式下映射静默不生效配置了 user_mapping 但漏配 tenant_mapping,映射因租户未解析而被忽略。两者一并配齐;用 dry-run 端点看 tenant.mode 是否为 blocked。
roles 没有变成内部角色sync_roles 未开启,或 role_mapping 键名与断言 roles 不匹配(区分大小写)。看交换响应 synced.disabled / synced.roles.unmapped 回执定位。
attrs 没生效(问数拒答“未配置数据属性”)sync_user_attrs 未开启 / attribute_mapping 未配该键 / 值不是字符串数组。L1 回执里 synced.attrs 为空即定位;确认值是字符串数组。
交换成功但数据不过滤行过滤策略未配置 / 策略表名与物理表名不符 / 用户是管理员或在豁免名单。管理员在「数据查询 > Schema > 行级权限」用「权限试算」查看最终 WHERE 与命中行数。
10

上线前安全检查

示例工程用于验证链路,生产接入必须收紧身份与权限边界。

不要直接照搬示例的身份传递方式。当前 /api/auth/token 接受浏览器传入的用户和角色,且默认角色为 system:admin。生产环境应由第三方后端根据已验证的登录 Session 决定身份与权限。

生产接入检查清单

  • 第三方系统先完成自身认证,后端从可信 Session 获取 user_id、租户、姓名和角色,忽略客户端声明的身份字段。
  • 使用稳定的用户唯一标识;显示名可以修改,但不要将显示名作为唯一用户键。
  • ISSUER_SECRET 仅存在服务端密钥管理中,不下发浏览器、不写日志、不提交 Git,并建立轮换机制。
  • 按最小权限分配角色,移除示例默认的 system:admin;不同租户使用正确的 tenantId 隔离。
  • 生产启用 HTTPS,allowed_origins 精确配置,SebAgent 地址使用固定白名单,保持服务器时间同步。
  • 避免在普通 API 的 URL 中传播 Token;当前 iframe 嵌入按既有协议使用 ?token=,并防止 Token 被写入前端日志。
  • 断言 TTL 控制在 60 秒以内;每次签名生成新 jti,不缓存复用断言。
  • 评审 attribute_mapping 键清单:断言只放行过滤必需的数据属性,不要把手机号、身份证等敏感属性引入断言(只有映射左键里的键会进入身份层)。
  • 确认缺属性拒答文案对客户可见措辞可接受(“请联系管理员处理”),并在上线前用 dry-run 端点 + 权限试算走一遍全链路。