变更说明(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 对话框嵌入。本文与当前示例工程的配置和调用链保持一致。
一次页面加载,完成整个登录链路
接入总览
先理解浏览器、集成后端和 SebAgent 各自负责什么。
本工程是一个独立的第三方门户示例。前端负责读取配置和挂载 iframe;Flask 后端保管 issuer secret、签发 assertion 并换取 Token;SebAgent 负责校验身份、JIT 开通以及签发 v2 Token。
本工程使用“后端对后端换 Token + iframe 嵌入”,不使用浏览器表单 POST /auth/sso 的 Cookie 登录方式。
准备工作
先拿到后台生成或确认的接入信息,再修改本地配置。
后台生成 ISSUER_ID 和 ISSUER_SECRET,用于标识第三方系统并签名 assertion。
确认第三方后端实际可达的地址。该地址同时用于 JWT 的 aud,必须与后台 audience 配置匹配。
将浏览器访问地址的协议、主机和端口完整加入 issuer 的 allowed_origins,不能使用通配符。
Python 3.10+、Node.js 20+、npm 10+,并确保 6001、6002 端口以及 SebAgent 服务可用。
配置一致性是接入成功的关键:COWAGENT_BASE_URL 要同时满足“后端能访问”和“与后台受众匹配”;FRONTEND_ORIGIN 要与浏览器地址栏中的 Origin 完全一致。
配置环境变量 .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 历史或公开日志,应立即在后台轮换,而不是只删除本地文件。
配置前端 src/config.ts
页面标题、品牌、用户身份、租户和对话框外观集中在这里。
页面没有登录表单,加载时会按照 appConfig 自动换取 Token 并挂载 AIP-TALK。修改后 Vite 会热更新。
| 配置项 | 类型 | 当前工程示例 | 说明 |
|---|---|---|---|
pageTitle | string | 云数工业 · AIP-TALK | 浏览器标签页标题。 |
logoUrl | string | /yunshu-logo.png | 标题栏 Logo。public/ 下的文件以 / 开头引用。 |
logoAlt | string | 云数工业 YUNSHU INDUSTRY | Logo 替代文本,用于无障碍和图片加载失败场景。 |
cowagentBaseUrl | string | 空字符串 | 建议留空,前端通过 /api/config 使用后端 .env 中的地址;填写后会覆盖后端默认值。 |
userId | string | yunshu | 第三方外部用户 ID,进入 JWT 的 sub。生产环境应使用稳定且唯一的工号或用户 ID;留空时后端生成带时间戳的 demo 用户。 |
tenantId | string | tnt_81598fe488b508ba | 第三方外部租户 ID,进入 JWT 的 tid;留空时后端使用 demo-tenant。 |
displayName | string | yunshu | AIP-TALK 用户显示名,进入 JWT 的 name;留空时使用用户 ID。 |
theme | 'light' | 'dark' | light | 对话框初始主题,iframe ready 后同步。 |
lang | string | zh | 对话框初始语言,可选 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= 覆盖对应配置。它们用于测试,不应作为生产环境传递用户身份的机制。
第三方用户如何登录
用户不需要再次输入密码;第三方身份通过签名 assertion 传递给 SebAgent。
移动端可横向滚动查看时序图。每一步的文字说明如下。
没有账号密码登录。页面启动后直接使用 config.ts 中的 userId、tenantId 和 displayName 自动完成 SSO。
应先完成你们自己的登录认证,再由服务端从 Session 或身份上下文中取得用户、租户和角色,不能信任浏览器自行声明。
用户身份在链路中如何变化
前端传入的是“外部身份”,SebAgent 返回的是“内部身份”。同一个稳定的 userId 会映射到同一个内部用户;留空则可能每次创建新的 demo 用户。
集成后端实际执行的操作
server/app.py 接收 user_id、tenant_id、name 等字段并校验 ID 格式。
server/sso.py 写入 iss、sub、tid、aud、iat、exp、jti、name、email 和 roles,再使用 ISSUER_SECRET 做 HMAC-SHA256 签名。
后端请求 POST {COWAGENT_BASE_URL}/api/v1/sso/token,JSON 请求体为 {"assertion": "..."}。
前端拿到 Token 后创建 /embed/aip-talk?token=... iframe;收到 cow:ready 后同步主题和语言,页面状态变为“已就绪”。
角色注意事项:当前示例在 roles 缺省时使用 system:admin,仅用于联调。并且 SebAgent 只在首次 JIT 创建用户时应用角色;复用同一外部用户 ID 时,修改配置不一定会改变已有角色。
多用户映射(user_mapping)
第三方系统有多个用户时,把每个外部用户固定绑定到 SebAgent 内部用户,不再依赖 JIT 现场创建。
上一节的 JIT 自动开通适合快速联调:未命中的外部用户会被现场创建为 ext:<issuer>:<sub> 形式的账号。当第三方系统要求“谁是谁”完全受控——例如 hkgc001 发行方下的 test001-hkgc、hkgc 等账号必须各自对应租户里的真实成员——应改用显式 user_mapping。整个配置由三方协作完成:
企业AI大脑(SebAgent)租户管理员在「系统管理 > 用户管理」中为本租户逐个创建用户(或复用现有用户)。用户列表的“用户ID”列即为 usr_ 前缀的内部用户 ID,复制备用。
第三方系统把「外部用户 ID(JWT 中的 sub,对应示例工程 config.ts 的 userId)→ 内部用户 ID」整理成一个 JSON 对象,交给 SebAgent 系统管理员。
admin 打开「系统管理 > 第三方集成设置」,在发行方列表中选中对应发行方(如 hkgc001),将 JSON 粘贴进 user_mapping(JSON 对象) 输入框,点击「保存映射」。保存即时生效,无需重启服务。
{
"test001-hkgc": "usr_ede5e7366f202571",
"test002-hkgc": "usr_c4ff9c0a65b293e8",
"hkgc": "usr_641667aab88987d0",
"hkgc-r": "usr_d00ffd02fab4fb9c"
}
红框处粘贴第三方提供的映射 JSON 并点击「保存映射」;同一面板还可维护 tenant_mapping 与开通策略。
命中与回退规则
键 = 断言中的 sub(第三方传入的 userId);值 = 内部 usr_ 用户 ID。被映射用户必须属于 tenant_mapping 解析后的目标租户,否则视为未命中并继续后续解析。
user_mapping 命中优先于 SSO metadata 隐式链接和 JIT 自动创建;事后补配或修改的映射在下一次 Token 交换时生效。
关闭「自动创建未映射用户(JIT)」后,仅 user_mapping 命中或历史已开通的用户可登录,其余一律拒绝——生产环境推荐关闭。
保存时前端会校验必须是 JSON 对象且所有值为字符串;格式错误会直接提示,不会写入。
映射变更的影响范围:「保存映射」只影响之后的 Token 交换;已签发且未过期的 v2 Token 仍携带旧身份,等待其自然过期或重新登录即可切换到新映射。
数据权限:角色同步与行级数据权限
第三方系统在断言里声明用户角色与数据属性,SebAgent 管理员一次性配置映射与绑定,权限随登录自动生效、随第三方变更自动同步。
上一节的 user_mapping 解决“谁是谁”;本节解决“谁能看哪些数据”。整条链路为 Claims → Attributes → Bindings → Filters:断言声明(Claims)经映射落成用户属性(Attributes),管理员把属性绑定到表的过滤列(Bindings),查询时由执行层自动注入行级过滤(Filters)。
三方分工:第三方开发负责断言带 roles/attrs;SebAgent 管理员负责映射与绑定;最终用户无感。
参数定义速查(配置前先认清每个字段)
三张表覆盖本链路的全部参数:断言里第三方要传的、发行方卡片里管理员要配的、行过滤策略里绑定要写的。所有字段名区分大小写。
| 断言字段(JWT payload) | 类型 | 必填 | 说明与传递方式 | 示例 |
|---|---|---|---|---|
iss | string | 必填 | 发行方 ID,必须与 SebAgent 后台配置的 issuer_id 逐字一致;dry-run 端点也从这里解析发行方。 | "yunshu-os" |
sub | string | 必填 | 外部用户唯一 ID,长期稳定不变;用于 user_mapping 命中或 JIT 建号。不要用显示名。 | "zhangsan" |
tid | string | 必填 | 外部组织/租户 ID;用于 tenant_mapping 命中或自动建租户。 | "acme" |
aud | string | 必填 | 接收方基础 URL;必须命中发行方配置的 audience 或 additional_audiences 之一。 | "http://111.9.54.6:9899" |
iat / exp | int(Unix 秒) | 必填 | 签发时间 / 过期时间;TTL(exp-iat)≤ 60 秒,双方时钟需同步。 | 1761200000 / 1761200060 |
jti | string | 必填 | 断言唯一编号,防重放;每次签名随机生成,不缓存复用。 | "9f2c...hex" |
name / email | string | 建议 | 显示名与邮箱;开启「同步属性」时更新用户资料。 | "张三" / "zs@acme.com" |
roles | string[] | 可选 | 外部角色名(不是 SebAgent 内部角色 ID),经 role_mapping 翻译;未映射的被忽略。发行方未开 sync_roles 时,仅在 JIT 首次建号时作为角色来源。 | ["ws_operator"] |
attrs | object<string, string[]> | 可选 | 用户数据属性——行级权限的取值来源。键须出现在 attribute_mapping 左键中才会进入身份层;值统一为字符串数组(标量会被规范化为单元素数组,null 视为空数组)。 | {"workshops": ["一车间", "二车间"]} |
| 发行方「权限同步」字段 | 类型 | 缺省 | 说明 | 示例 |
|---|---|---|---|---|
sync_roles | bool | 关闭 | 开启后,断言 roles 经 role_mapping 翻译后每次登录覆盖式同步:新增的补授、消失的回收(只回收同步来源角色,手工授予不受影响)。 | 开启 |
role_mapping | JSON 对象 | 空 | 外部角色名 → 内部角色 ID。目标角色必须真实存在,否则按未映射处理(不产生幻影授权)。开启 sync_roles 时至少配置一条。 | {"ws_operator": "tenant:user"} |
sync_user_attrs | bool | 关闭 | 开启后,断言 attrs 经 attribute_mapping 翻译写入用户数据属性;上次同步但这次未声明的键被移除,手工配置的同名键不受影响。 | 开启 |
attribute_mapping | JSON 对象 | 空 | 断言 attrs 键 → 内部属性键(可改名归一)。只有左键列出的键会进入身份层——这是防止手机号等敏感属性被意外引入的边界。 | {"workshops": "workshops"} |
| 行过滤规则字段 | 取值 | 说明 | 示例 |
|---|---|---|---|
column | 物理列名 | 过滤列;必须是表 schema 中真实存在的列(幻影列直接拒绝,防注入)。 | workshop_id |
op | 见下方操作符表 | 比较操作符,白名单枚举,不接受任意 SQL 片段。 | in |
value_source | user_attr / literal | 值来源:user_attr = 取当前用户的数据属性(主用,随登录动态刷新);literal = 固定值(兜底,无第三方集成的小场景)。 | user_attr |
attr_key | 属性键名 | value_source=user_attr 时引用;用户缺该属性 = 明确拒答(fail-closed),而不是静默返回空表。 | workshops |
value | string[] | 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 | 闭区间过滤,如日期区间 |
同一张表配多条规则时按交集生效(fail-closed 方向);同表多策略命中同样取交集,不会互相放宽。
超级管理员与租户管理员天然直通(便于排障);策略可另配豁免角色/用户名单。普通用户无任何绕过路径,缓存也按参数指纹隔离——不同属性值的用户互不可见对方结果。
①SSO 同步:断言 attrs 经 attribute_mapping 落入(随登录自动刷新);②手工维护:租户管理员在「系统管理 > 用户管理」编辑用户的「数据属性」。两者可混用,手工值不被 SSO 回收(同名键以同步为准)。
一、配置角色与属性同步(发行方「权限同步」区)
admin 进入「系统管理 > 第三方集成设置」,在发行方列表选中目标发行方(如 yunshu-os),展开「权限同步」区。
勾选「同步角色(sync_roles)」,在 role_mapping 中把外部角色名映射到内部角色 ID。未映射的外部角色会被忽略(不报错),映射到不存在的内部角色同样按未映射处理,不会产生幻影授权。
勾选「同步用户属性(sync_user_attrs)」,在 attribute_mapping 中把断言 attrs 的键映射为内部属性键(可改名归一,如第三方叫 workshops、内部统一叫 workshops)。只有出现在映射左键里的属性才会进入身份层,断言里多带的其他键被丢弃——这是防止敏感属性被意外引入的边界。
保存即时生效,无需重启。用下文「三级探针」的 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 中声明。
按上一节开启 sync_user_attrs 并配置 attribute_mapping;第三方后端签名时写入 attrs: {"workshops": ["一车间", "二车间"]}(值统一为字符串数组)。
租户管理员打开「数据查询 > Schema > 行级权限」TAB,选中数据源后新建策略:表 prod_records → 添加规则:列 workshop_id(列名下拉,含数据字典业务名)→ 操作符 in → 值来源「用户属性」→ 属性键 workshops。也可用预设模板「按车间」一键生成同构规则,或用「探查真实值」对该列做 SELECT DISTINCT 后点选,杜绝手输错别字。
用户 A(workshops=["一车间"])问“各车间本月产量”→ 结果只含一车间,查询被自动改写为 WHERE workshop_id IN (?) 并参数化传值;用户 B 未配置该属性 → 收到明确拒答(见下方文案),而不是静默看到空表。
「行级权限」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 秒确认真相
用示例工程 peek_issuer_id() 或 jwt.io 解开 payload,确认 attrs 键名、aud、exp 正确。
用断言换 Token,响应里的 synced 回执就是角色与属性映射的落地明细。
拿 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 源码。
启动与验证
分别启动集成后端和 Vite 前端,然后检查自动登录结果。
在工程根目录执行以下命令。
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 接口(由工程自动调用)
/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 天)。
常见故障排查
优先检查地址、Origin、受众和身份配置是否一致。
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| Cannot connect to CowAgent | SebAgent 未启动、网络不可达或地址端口错误。 | 从运行集成代理的机器验证 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/token | 6002 后端未启动,或 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 与命中行数。 |
上线前安全检查
示例工程用于验证链路,生产接入必须收紧身份与权限边界。
不要直接照搬示例的身份传递方式。当前 /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 端点 + 权限试算走一遍全链路。