AIP-TALK 集成文档
开始配置
指南目录

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

接入总览

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

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

系统架构与令牌流向Browser → Proxy → CowAgent
AIP-TALK 第三方接入架构图 第三方浏览器调用集成后端获取 Token,集成后端使用签名 assertion 调用 CowAgent,最后浏览器通过带 Token 的 iframe 加载 AIP-TALK。 IDENTITY & TOKEN FLOW 第三方浏览器 Flask 集成代理 CowAgent / 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
CowAgent 服务地址

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

C
前端 Origin 已登记

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

D
本地开发环境

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

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

03

配置环境变量 .env

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

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

环境变量来源作用与配置要求示例 / 默认值
COWAGENT_BASE_URL后台提供CowAgent 根地址。后端调用 SSO 接口,并将其作为 assertion 的 aud;必须匹配后台的 audience 或 additional_audiences。https://cowagent.example.com
ISSUER_ID后台生成第三方 issuer 唯一标识,对应 CowAgent 的 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://cowagent.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 传递给 CowAgent。

单点登录完整时序SSO assertion → JIT → v2 Token → iframe
第三方用户登录 AIP-TALK 时序图 用户打开第三方页面,浏览器请求集成后端,后端签名 assertion 并调用 CowAgent。CowAgent 校验、自动开通用户并返回 Token,浏览器最后加载带 Token 的 AIP-TALK iframe。 第三方用户 浏览器 / 前端 Flask 集成后端 CowAgent 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 或身份上下文中取得用户、租户和角色,不能信任浏览器自行声明。

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

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

第三方身份userId / tenantIddisplayName 作为用户姓名
签名 assertionsub / tid / name外加 iss、aud、exp、jti、roles
CowAgent 内部身份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
向 CowAgent 交换 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,仅用于联调。并且 CowAgent 只在首次 JIT 创建用户时应用角色;复用同一外部用户 ID 时,修改配置不一定会改变已有角色。

06

启动与验证

分别启动集成后端和 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": "<cowagent-v2-token>",
  "user_id": "usr_...",
  "tenant_id": "ext:yunshu-os:tnt_...",
  "roles": ["tenant:user"],
  "expires_in": 3600
}

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

07

常见故障排查

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

现象常见原因处理方法
Cannot connect to CowAgentCowAgent 未启动、网络不可达或地址端口错误。从运行集成代理的机器验证 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 创建,角色只在首次创建时应用。按 CowAgent 管理流程调整已有用户权限;联调时可使用新的测试用户 ID 验证首次开通。
08

上线前安全检查

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

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

生产接入检查清单

  • 第三方系统先完成自身认证,后端从可信 Session 获取 user_id、租户、姓名和角色,忽略客户端声明的身份字段。
  • 使用稳定的用户唯一标识;显示名可以修改,但不要将显示名作为唯一用户键。
  • ISSUER_SECRET 仅存在服务端密钥管理中,不下发浏览器、不写日志、不提交 Git,并建立轮换机制。
  • 按最小权限分配角色,移除示例默认的 system:admin;不同租户使用正确的 tenantId 隔离。
  • 生产启用 HTTPS,allowed_origins 精确配置,CowAgent 地址使用固定白名单,保持服务器时间同步。
  • 避免在普通 API 的 URL 中传播 Token;当前 iframe 嵌入按既有协议使用 ?token=,并防止 Token 被写入前端日志。