UNIDOC / KNOWLEDGE IN MOTION

OmniDoc 自动登录与 UniDoc 接入

从理解，到动手实现。步骤、协议与可复制的示例，都在这份文档中。

更新：2026-09-19。适用产品：https://app.unidoc.top/。本说明对应 UniDoc 的顶层产品登录；其他产品、桌面容器和 UniMail 邮件 iframe 各自验收。

用户会看到什么

在同一个浏览器或共享持久会话的 OmniDoc 客户端中，先登录 OmniDoc，再打开 UniDoc。若 Connect 能识别主站会话且用户已经授予 UniDoc 所需权限，UniDoc 在安全的首次启动阶段自动完成一次授权往返，进入原页面。

已有 UniDoc 会话继续使用原账户。首次授权、主站未登录或暂时连接失败时，页面保留手动登录按钮，按钮提示下一步；不会反复刷新。点击按钮继续登录时，不默认强制选择账户。明确切换账户的集成调用仍可使用 prompt=select_account。

公开分享和嵌入页面不触发自动登录；用户已打开自己的文档、恢复草稿或开始编辑后也不会自动跳走。手动登录沿用原来的登录前文档检查点。空白入口 /?blank=1 登录后仍回到空白入口。

产品接口

接口	行为
`GET /auth/session`	保持已有账户字段，增加不含凭据的 `sso` 对象
`GET /auth/login?mode=silent&return_to=%2F%3Fblank%3D1`	服务端创建一次性 state、nonce 和 PKCE，授权请求追加 `prompt=none`
`GET /auth/login?return_to=%2F`	手动继续登录，缺省不强制 prompt
`GET /oauth/callback`	校验回调、ID Token 和 UserInfo，持久化成功后才发会话 Cookie
`POST /auth/logout`	撤销本产品会话、取消当前浏览器登录事务，保持主动退出偏好

状态示例：

{
  "authenticated": false,
  "userId": "",
  "sso": {
    "supported": true,
    "automatic": true,
    "status": "ready"
  }
}

前端只有同时收到 supported: true、automatic: true、status: ready，且当前文档允许安全跳转，才尝试一次。旧后端不提供该对象时继续使用手动入口。状态和授权响应禁止缓存。

防循环、退出与原页面恢复

自动尝试先设置 5 分钟冷却。服务端使用独立的 host-only、HttpOnly、Secure、SameSite=Lax Cookie；浏览器另保留不含凭据的会话级冷却时间。浏览器拒绝会话存储时不自动跳转，避免 Cookie 被阻止后出现循环。

只有已校验事务与 state 的错误回调能记录 login_required、consent_required、interaction_required 或 failed。提供方原始错误描述不会进入静默回退地址。错误 state、重复回调、code 与 error 同时存在都不能创建会话。

主动退出成功后记录最长 30 天的 signed_out 偏好，刷新仍保持退出。明确点击登录清除偏好；用户主动清理 Cookie 后该偏好随之消失。退出存储失败会反馈错误，不宣称成功。

退出或新登录排在旧授权码交换之后处理时，服务端仍能通过原事务关联撤销旧流程生成的会话。既有回调验证、稳定 issuer + sub 身份映射和 backchannel logout 保持启用。

return_to 只接受站内路径，排除认证入口与回调，防止重定向循环。URL fragment 只在本标签页短时保存和恢复，不传给 Connect；分享 URL 本身不触发自动登录。主站切换账号不会擅自替换已经登录的 UniDoc 账户。

部署与同事配合

继续使用 UniDoc 自己已注册的客户端、scope、精确回调 https://app.unidoc.top/oauth/callback 及既有服务端密钥。不能借用 UniPPT 的 client_id、secret、Cookie 或 token。

先更新后端，再更新前端。运行脚本继续通过 .js.udoc 发布。部署沿用现有会话签名及持久存储，不为本功能清空账户数据或要求全体用户重新登录。

需要回退自动尝试时，将后端 UNIDOC_OIDC_AUTO_LOGIN=false 后重启服务；手动 OIDC 登录及账户隔离继续工作。

桌面客户端应让主站、Connect 与产品使用同一个持久化 Chromium/CEF RequestContext。若主站已登录但 Connect 返回 login_required，由 OmniDoc 团队检查主站到 Connect 的会话建立和浏览器上下文。缺少产品授权时应返回 consent_required，由用户明确确认，不能绕过。

验收范围

本轮包含隔离的签名 OIDC 提供方与真实 Rust HTTP 联调、浏览器启动及草稿回归、公网接口和文件验证。隔离账户测试不代表真实 OmniDoc 主站会话、首次授权或桌面 CEF 已完成验收。

真实账户验收需分别确认：已有主站会话与产品授权时静默成功；主站未登录时一次回退；主动退出后刷新不重登；手动继续登录能恢复；公开分享不被阻挡；本地未保存文档和返回位置不丢失。全产品账号切换同步、全局退出通知和 UniMail iframe SSO 不在本轮实现范围。

协议依据：OpenID Connect Core 授权请求。工程输入为 UniPPT 的《OmniDoc 产品自动登录接入说明》2026-09-19 版；本页仅描述 UniDoc 的实际实现与验收边界。