方式二:iframe 嵌入接入(工作台免登集成)
目标:把我们的分析工作台(XRD/Raman/NMR/MS/XPS/IR/TEM)直接嵌入贵司产品页面,贵司用户免登录、免注册使用,每用户数据完全隔离,我们的登录页全程不出现。适合贵司自建 SaaS 或内部平台的产品内嵌场景。
两种方式平行可选、可同时开通,用户只需在贵司平台登录一次(用贵司自己的登录系统),随后点开分析工具即直接进入工作台。
核心机制
- 映射账号(自动建档):每个贵司用户在我们平台对应一个映射账号(挂贵司专属机构),首次打开时自动创建,贵司无需管理我们这边的任何账号——数据按账号天然隔离
- 单次短票据:嵌入用一次性登录凭证(60 秒有效、消费一次即失效),避免长时效 Token 暴露在地址/Referer 中的风险;工作台校验票据后立即种下会话 Cookie
- 服务端换票:AppSecret 只在贵司后端保管,前端零凭据——iframe 地址由贵司后端用 AppID/Secret + external_user_id + target_project 换得
三层凭证与有效期(易混,先看这张表)
| 凭证 | 用在哪 | 有效期 | 过期了会怎样 |
|---|---|---|---|
| SSO 票据(一次性) | 仅"打开 iframe"一瞬间——换票后毫秒级即被消费,之后不再出现 | 60 秒 | 正常流程永远碰不到(开门后即作废);仅"拿到地址拖 60 秒以上才打开"这一种异常会失效,重新换票即可 |
| 会话 Cookie(登录状态) | 用户使用全程:上传、查报告、跑分析的登录态都是它 | 7 天,过程内自动续期 | 超 7 天未访问才会过期:工作台内容区显示"登录状态已过期"提示页(不白屏、外页无反应);贵司重新换票 + 设 src 即恢复,历史数据与任务不丢 |
| 内部 Access Token | 我们内部服务之间,不出网关,贵司无感 | 15 分钟,自动静默续期 | 无任何影响,代码自动处理 |
一句话:票据只管"进门",Cookie 管"使用"。60 秒是给泄露上封印的安全垫,不是给用户计时的闹钟——用户在使用过程中(哪怕连续用几天)永远不会遇到"票据过期"。
对接实施分五步(从拿到凭证到上线)
- 第 0 步 · 签约与开通:我方发放 AppID + AppSecret(贵司后端保管);签约时确认三件——目标工作台项目(
target_project)、贵司嵌入页面域名(我方 frame-ancestors 白名单放行)、嵌入形态(推荐贵司加一条 CNAME 子域实现同站,见下方"浏览器兼容前提") - 第 1 步 · 后端换票接口(核心,约 5 行):贵司后端实现一个内部接口——接收贵司已登录用户的 userId → 调我方
POST /v1/sso/partner-login(带 app_id/app_secret/external_user_id/target_project)→ 把返回的workbench_callback返回给前端。这是对接工作的全部核心(参考下方代码示例)。如需在我方页面显示贵司用户的名称(顶栏身份与报告"分析人"署名),换票时一并传display_name(可选,姓名/昵称/贵司规定的展示标识均可) - 第 2 步 · 前端挂 iframe:拿 iframe_url 设 iframe src。两个体验决策:① iframe 容器建议常驻(首开后不销毁,"打开工具"切显隐)→ 同一用户二次进入零闪烁;② 每次点开工具入口时调一次后端换票接口、拿新地址设 src(票据一次性,不复用缓存)
- 第 3 步 · 联调验收(半天):核对五件事——① 首见用户打开直接进工作台(全程不出现我方登录页);② 同一用户二次打开免登命中;③ A/B 两用户各自打开看到各自数据;④ 同一票据地址第二遍使用被拒绝;⑤ Chrome + Safari 各过一遍
- 第 4 步 · 上线前确认:白名单/CNAME 我方配置完成 → 双方一起做一次真浏览器 iframe 内实测 → 贵司生产环境启用正式 Secret
集成流程(四步)
- ① 用户在贵司平台正常登录(贵司自己的登录系统,与我们无关)
- ② 用户打开"分析工具"入口 → 贵司后端自动调
POST /v1/sso/partner-login(见下方契约) - ③ 我们查/建映射账号 → 签发单次短票据,返回拼好的完整工作台地址(
workbench_callback) - ④ 贵司前端把该地址直接作为 iframe src——用户无感进入分析工作台开始使用
贵司后端参考代码(~50 行)
app.post("/api/open-tool", async (req, res) => {
const resp = await fetch("https://api.cleerscience.com/v1/sso/partner-login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
app_id: "app_xxx", // 我们发放给贵司的 AppID
app_secret: process.env.CLEER_SECRET, // Secret 仅贵司服务端环境变量
external_user_id: req.session.userId, // 贵司平台用户唯一标识
display_name: req.session.userName, // 可选:展示名(我方页面顶栏/报告署名显示)
target_project: "dsh-xrd" // 签约项目 key(示例为 XRD;SEM 客户为 cleer-sem-platform,以开通清单为准)
})
});
const data = await resp.json();
res.json({ iframe_url: data.workbench_callback });
});
// 前端(Vue 示例): <iframe :src="iframe_url" />每次用户打开分析入口都重新调一次换票接口(无用户交互、后端 ~1 秒内完成);票据是一次性的,不复用。
常见疑问
- 用户需要在我们这边注册账号吗? 不需要——首次打开时自动建档,贵司无需管理任何我们平台的账号
- 会看到别人的数据吗? 不会——每个贵司用户对应一个独立映射账号,数据按账号隔离
- iframe 打开瞬间地址上的 ticket 是什么? 单次短票据(60 秒有效),不是密码或 Token,泄露无第二次机会
- 每次打开 iframe 都要换一次票据? 是,这是安全核心——票据一次性,由贵司后端自动执行,不会让用户等待
- 用户名怎么在我们这边显示? 换票时传
display_name(可选)——我方工作台顶栏与报告"分析人"栏即显示该名称;不传则显示 external_user_id。贵司改了用户名后下次换票带上新值即可自动更新,无需找我方 - 怎么统计自己平台每个用户的用量? 每次分析自动带 external_user_id 入账(与 API 方式同一账本),贵司按 ID 聚合即可出账单/报表
- 用户用着用着(上传/查报告时)登录会过期吗? 正常使用不会——会话 Cookie 7 天有效且过程内自动续期。极端情况(超 7 天未访问)过期时:正在运行的任务不受影响、数据不丢,工作台内容区显示"登录状态已过期"提示页;贵司前端重新调换票接口 + 重设 iframe src 即恢复,与"切换用户"是同一套代码
- 域名白名单? 需在接入协议里登记贵司嵌入页面的域名,防止第三方站点恶意嵌套;我们按签约清单自动放行
嵌入体验与换票纪律(重要)
换票是服务器对服务器的调用(贵司后端 ↔ 我们网关,约 1 秒),用户浏览器不参与、不可见;票据消费、会话建立全部在 iframe 内部完成。因此:
- 用户整页无感:贵司页面外壳(导航/浏览位置/其它面板)全程不动,只有 iframe 区域加载工具内容(首次 1–3 秒,之后更快)。这不是传统 OAuth 的"跳走再跳回",用户从未离开贵司页面
- 预取加速(推荐):贵司可在用户进入页面时后台预换票据、点击时即时打开;也可在点击时再换(约 1 秒内完成),两种都行
- 切换用户必须换票:贵司平台 A 用户登出、B 用户登录后打开工具时,必须重新调 partner-login 为 B 换新票并重新设置 iframe src——不复用旧 iframe 内容、不缓存旧地址。守住这条纪律就不会出现会话串号
- 票据 60 秒有效:换票与设置 iframe src 之间不要有延迟(不要写入数据库或队列后再使用)
联调常见报错与误区排查(打不开/进错页先看这里)
- 手工在浏览器打开我们某工作台域名,要求登录? 这是预期行为——你们的用户进入工具的唯一通路是
partner-login返回的workbench_callback(每次都是新地址),绕过换票直开域名没有会话。请始终以前端 iframe 加载返回地址的方式进入,不要收藏/手敲工作台域名 - 把 workbench_callback 复制到浏览器打开,显示"请从合作方平台进入"引导页? 票据 60 秒内有效、一次性——手工复制粘贴的超时或已被前一次加载消费掉会是这个效果,不是故障;回到 iframe 流程重新换票即可。正确用法是前端拿到接口响应后立即赋值 iframe src(一两秒内完成)
- 本地联调用哪个接口地址? 不区分环境——联调与生产都调
https://api.cleerscience.com/v1/sso/partner-login,AppID/Secret 同一组 - 打开后进入了别的工作台 / 返回 workbench_client_not_found?
target_project决定目标——参考代码里的dsh-xrd仅是 XRD 示例,请替换为开通清单中你们签约的项目 key(SEM 为cleer-sem-platform)
上线前必读:iframe 会话的浏览器兼容前提
跨站 iframe 内的会话 Cookie 受现代浏览器第三方 Cookie 限制(Chrome/Safari 对跨站嵌入逐步禁用第三方 Cookie)。稳妥落地方案(接入时二选一,签约时确认):
① 子域同站(推荐):贵司为工作台加一条 CNAME(如
② 我们侧调整会话 Cookie 属性并逐浏览器实测(Chrome/Edge 可行,Safari 受限)。上线前我们与贵司一起做一次真浏览器 iframe 内实测(Chrome + Safari 各一遍)作为验收步骤。
① 子域同站(推荐):贵司为工作台加一条 CNAME(如
sem.贵司域名.com 指向我们工作台),变跨站为同站,所有浏览器通吃,仅贵司加一条 DNS 记录、我们配合签证书;② 我们侧调整会话 Cookie 属性并逐浏览器实测(Chrome/Edge 可行,Safari 受限)。上线前我们与贵司一起做一次真浏览器 iframe 内实测(Chrome + Safari 各一遍)作为验收步骤。
上述兼容工作不影响接口契约本身——partner-login 的调用方式两种方案下完全一致。