已有系统接入
自带账号、登录和权限的应用怎样把 OpenMax 身份变成自己系统里能用的登录用户:完整链路、接入前检查清单、接入策略表和首次进入的处理顺序。
已有系统接入
这页写给本来就有用户表、登录页和权限模型的系统(如 Leantime、各类自部署工具)。登录解决的是「拿到一个可信的 OpenMax 身份 (org_id, member_id)」,到此为止;这页解决「这个身份怎样变成你系统里一个能用的登录用户」。
两者的关系:
- 和登录的关系:登录里的会话规则(流程单次使用、会话不超过 token 过期、过期重新授权)同样约束你系统的原生会话。你用自己的会话机制登录用户,但它的寿命跟着 OpenMax 授权走。
- 和「不做的事」里的 SSO 的关系:平台不做统一单点登录 / 单点登出(不同步登录态、不通知退出、不替你建账号、不对接你系统自己的 IdP)。应用用 OpenMax 授权把 OpenMax 身份映射成本地账号,是应用自己的实现,允许也推荐,和这条不冲突。
完整链路
| # | 环节 | 谁负责 | 做完的标志 | 常见坑 |
|---|---|---|---|---|
| 1 | OpenMax 身份 | 外壳 + 授权页 | 成员已登录 Workspace,安装 active,入口 roles 可见;外壳打开 {url}{子路径} |
以为外壳会带身份参数(不会,见打开方式与地址「入口地址上的参数」) |
| 2 | 应用授权 | 应用(登录) | 回调核过 iss / state,换到 token,id_token 验过,org_id 在允许范围内 |
iframe 内 cookie 属性不对,回调找不到流程;iPhone / Safari 上嵌入时在 iframe 里跳转登录(必断,改用登录「嵌入时登录」) |
| 3 | 应用账号 | 应用 | 按 (issuer, org_id, member_id) 找到绑定,或按策略(见下文「接入策略表」)创建 / 拒绝 |
按邮箱自动合并到已有账号(账号接管风险) |
| 4 | 原生登录态 | 应用 | 用你系统自己的会话机制登录这个账号;会话有效期 ≤ token 过期(见登录「会话有效期」) | 原生会话默认几天甚至「记住我」,比授权活得长 |
| 5 | 首次进入行为 | 应用 | 新用户拿到默认角色、进入约定的项目 / 工作区,落在一个保证能打开的页面 | 新手向导自动建项目;落地页是用户无权访问的项目 |
| 6 | 业务页可用 | 应用 | 核心页面能打开、数据可见、操作不报 403 | 账号建好了但不属于任何项目,处处 403 / 空白 |
账号已创建 ≠ 用户能用。第 3 步成功只说明「有这个人」;只有第 5、6 步也成立,接入才算完成。外壳的「接入详情」只确认它自己的两步(校验、打开地址),应用侧的步骤它看不到,永远不会标成完成。要用上线清单里「真实首次使用验收」的用例自己验收。
接入前检查清单
- ☐ 能配置对外地址 / base path(挂在
/leantime这类前缀下时,生成的链接、重定向、静态资源、cookiePath都带前缀,见打开方式与地址「地址组合示例」) - ☐ 能在不改核心代码的前提下加一个登录入口(插件 / 中间件 / 认证扩展点),用于登录里的
/auth/openmax/login和回调 - ☐ 用户表能存外部绑定
(issuer, org_id, member_id)(单独一张绑定表更好),且有唯一约束 - ☐ 能用程序方式「以某账号身份登录」(创建原生会话),并能把会话寿命设成不超过 token 过期
- ☐ 要 embed:能改
X-Frame-Options/ CSPframe-ancestors;会话 cookie 能设SameSite=None; Secure; Partitioned - ☐ 路由能容忍入口地址上的
theme/openmax_lang,对末尾斜杠的处理已知 - ☐ 原生登录入口怎么处理:保留密码登录(管理员兜底)还是隐藏;关闭自助注册,避免绕过 OpenMax 建账号
- ☐ 权限模型摸清楚:有哪些角色、项目 / 工作区成员关系怎么授予,新用户不属于任何项目时页面是什么表现
- ☐ 首次登录会触发什么:新手向导、自动建示例项目、欢迎邮件。列出来,决定关掉还是保留
- ☐ 应用内「退出登录」能跳到带
?signed_out=1的地址(不自动重新授权,见登录「错误处理」) - ☐ 一个部署服务一个组织还是多个:决定
org_id的放行规则(见登录「回调处理」里的核组织一步) - ☐ 已经填好下面的接入策略表,并经组织管理员确认
接入策略表(必填,接入前定下来)
每一项都要有明确答案,写进你的配置 / 文档。不允许「先按默认上线再说」。
| 决策项 | 选项 | 建议 |
|---|---|---|
| 账号开通 | A. 首次进入自动创建 B. 管理员手动预绑定(预先建好 (org_id, member_id) → 本地账号,未绑定的人进来只看到「请联系管理员开通」) |
全员都该用、无按人计费 → A;有席位 / 许可证 / 敏感数据 → B |
| 已有本地账号怎么关联 | 管理员预绑定;或用户先用原账号登录、再手动确认关联一次 | 不要仅凭邮箱自动关联已有账号(邮箱相同不代表同一个人,也不代表这个人有权接管该账号)。邮箱只用于展示和管理员核对 |
| 默认角色 | 新账号的系统角色 | 最低的「可用」角色(如普通成员 / 编辑者),不是管理员。org_role 只供参考(见登录「token 端点与令牌」);如果确实要把 OpenMax owner / admin 映射成应用管理员,写明规则并说明怎么回收 |
| 落到哪个项目 / 工作区 | 指定一个默认项目;或不加入任何项目,落到引导页 | 指定一个明确的默认项目(如「OpenMax 团队」)。不要默认打开 / 加入全部历史项目:历史项目可能包含新成员不该看到的数据 |
| 是否自动加入 | 自动加入默认项目;或只建账号,由项目管理员邀请 | 自动加入时写清加入的项目和角色;不自动加入时,首次进入页面必须告诉用户「找谁开通」 |
| 怎么撤销 | 应用内移出项目 / 停用账号;OpenMax 侧成员离开、安装停用 / 卸载 | 两侧都要有路径:应用内移除不应被下次自动加入「加回来」(自动加入只在首次创建时做一次);OpenMax 侧撤销后下次授权失败(access_denied)或 token 401,应用停用会话并显示无权限,本地账号停用而不是删除 |
| 首次落地页 | 个人工作台 / 欢迎页 / 默认项目首页 | 选一个对默认角色保证可打开的页面;首次进入不触发「创建项目」类向导 |
首次进入的处理顺序
- 授权回调拿到身份并核过组织(见登录「回调处理」)→ 查绑定。
- 已绑定:账号被停用 → 显示无权限页,不重试;否则登录。
- 未绑定:策略 B → 显示「请联系管理员开通」(带上 member_id,方便管理员绑定),不建账号;策略 A → 在一个事务里创建账号 + 绑定 + 默认角色 +(如约定)加入默认项目,用唯一约束防止两个标签页同时首次进入建出两个账号。
- 建原生会话(寿命 ≤ token 过期),跳到 returnTo。returnTo 是
/或用户无权访问的页面时,改去约定的首次落地页。
