OmniDoc 自动登录与 UniDoc 接入

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

用户会看到什么

普通首页 / 和空白入口 /?blank=1 默认尝试一次静默登录。主站仍登录、Connect 能识别同一浏览器会话且用户已授予权限时，UniDoc 自动恢复产品会话。主站未登录时返回游客编辑器，不反复跳转。

集成方可使用 /?auto_login=0 关闭该页面的自动尝试；原有 auto_login=1 入口继续兼容。仅在同一个浏览器或共享持久会话的 OmniDoc 客户端中，Connect 能识别主站会话且用户已授予所需权限时，才可能静默成功。返回时删除 auto_login=1 参数。

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

公开分享和嵌入页面不触发自动登录。首次进入时，用户已打开自己的文档、恢复草稿或开始编辑后不会自动跳走。已经登录的用户在编辑期间会每分钟核对一次服务端会话；产品 Cookie 到期时，先保存当前文档的本地检查点，再尝试静默恢复。隐藏或离线页面暂停周期检查。

产品默认 8 小时会话期限仍由服务端控制。恢复通过主站登录状态重新认证，不把旧凭据留在前端，也不把产品会话设为永久有效。检查点绑定原账号：另一个账号不能恢复它；主站要求交互时，用户手动登录原账号后可继续恢复。检查点保留 30 分钟。文档在保存期间发生修改会取消跳转，继续保留当前编辑页面。空白入口登录后仍回到空白入口。

产品接口

状态示例：

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

首次自动登录要求服务端同时提供 supported: true、automatic: true、status: ready，当前文档允许安全跳转，且 URL 未设置 auto_login=0。旧后端不提供该对象时继续使用手动入口。状态和授权响应禁止缓存。

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

自动尝试先设置 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。

产品 SSO 后端已经提供这些接口时，本轮登录恢复只需更新前端。运行脚本继续通过 .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 的实际实现与验收边界。