Third-party integration · Client guide
AIP-TALK
客户端开发指南
从后台下发的接入参数开始,完成第三方用户单点登录、JIT 自动开通和 AIP-TALK 对话框嵌入。本文与当前示例工程的配置和调用链保持一致。
一次页面加载,完成整个登录链路
接入总览
先理解浏览器、集成后端和 CowAgent 各自负责什么。
本工程是一个独立的第三方门户示例。前端负责读取配置和挂载 iframe;Flask 后端保管 issuer secret、签发 assertion 并换取 Token;CowAgent 负责校验身份、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 端口以及 CowAgent 服务可用。
配置一致性是接入成功的关键:COWAGENT_BASE_URL 要同时满足“后端能访问”和“与后台受众匹配”;FRONTEND_ORIGIN 要与浏览器地址栏中的 Origin 完全一致。
配置环境变量 .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 历史或公开日志,应立即在后台轮换,而不是只删除本地文件。
配置前端 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 传递给 CowAgent。
移动端可横向滚动查看时序图。每一步的文字说明如下。
没有账号密码登录。页面启动后直接使用 config.ts 中的 userId、tenantId 和 displayName 自动完成 SSO。
应先完成你们自己的登录认证,再由服务端从 Session 或身份上下文中取得用户、租户和角色,不能信任浏览器自行声明。
用户身份在链路中如何变化
前端传入的是“外部身份”,CowAgent 返回的是“内部身份”。同一个稳定的 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,仅用于联调。并且 CowAgent 只在首次 JIT 创建用户时应用角色;复用同一外部用户 ID 时,修改配置不一定会改变已有角色。
启动与验证
分别启动集成后端和 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": "<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 自动调度刷新;重新加载页面会重新执行交换。
常见故障排查
优先检查地址、Origin、受众和身份配置是否一致。
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| Cannot connect to CowAgent | CowAgent 未启动、网络不可达或地址端口错误。 | 从运行集成代理的机器验证 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 创建,角色只在首次创建时应用。 | 按 CowAgent 管理流程调整已有用户权限;联调时可使用新的测试用户 ID 验证首次开通。 |
上线前安全检查
示例工程用于验证链路,生产接入必须收紧身份与权限边界。
不要直接照搬示例的身份传递方式。当前 /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 被写入前端日志。