SSO 统一身份认证集成
SSO（单点登录）让接入的业务系统通过统一身份认证确认用户身份。本文先说明成员如何登录，再说明管理员与接入开发人员需要准备什么。SSO 确认“你是谁”，业务系统仍需独立判断“你能访问什么”。
成员如何使用统一登录
- 打开要使用的业务系统，点击该系统提供的 登录 或统一登录入口，由业务系统发起认证。
- 跳转到 Duogex 统一身份认证页后，确认站点属于组织提供的正式地址，并在 所属租户 中选择自己的组织。
- 在 登录账号 中填写用户名，或组织已支持的手机号，输入 登录密码，点击 登录。密码框旁的图标可切换密码显示，公共场合注意遮挡。
- 若出现应用授权确认页，核对应用和请求范围，按组织要求决定是否继续。
- 等待返回原业务系统，核对姓名、组织及目标页面，再开始办理业务。
统一身份认证页的地址形式为 https://admin.duoge.work/token/login。是否可直接访问该路径取决于正式环境的认证反向代理配置；接入时应由业务系统发起完整授权流程。独立打开登录表单不能替代客户端授权请求，也不能保证登录后返回指定系统。
如果浏览器已有有效的统一认证会话，某些接入系统可能无需再次输入密码；是否免登录还取决于会话、租户、客户端及授权策略。登录过管理后台不等于已建立可供所有系统复用的 SSO 会话。
与企微、钉钉登录有什么不同
| 方式 | 本文中的用途 |
|---|---|
| SSO 统一身份认证 | 外部业务系统接入 Duogex 的认证服务，通过授权流程获得用户身份 |
| 企微、钉钉登录 | 用户使用第三方平台身份登录 Duogex，需相应平台配置和账号关联 |
| API 服务调用 | 系统按接口授权访问数据；服务身份调用不等于成员完成了浏览器登录 |
管理员：接入前准备
先确认集成方向：本文介绍“其他系统使用 Duogex 统一身份认证”。若要求 Duogex 使用另一家身份提供方登录，需要另行核对适配能力，不能直接套用本文的客户端配置。
由平台管理员和接入系统负责人确认以下内容，再在有权限的 终端管理 等实际客户端登记入口维护配置。具体入口参阅终端与在线令牌管理。
| 登记内容 | 要求 |
|---|---|
| 目标系统与负责人 | 每个接入系统明确用途、维护人和环境，避免共用不明客户端 |
| 客户端标识与凭据 | 为服务端接入登记专属 client_id 与 Secret，Secret 仅保存在接入服务端 |
| 授权类型 | 浏览器用户登录采用 authorization_code；按接入合同使用 S256 PKCE |
| 回调地址 | 登记接入系统实际接收授权结果的完整 HTTPS 地址，协议、主机、端口和路径保持一致 |
| 租户 | 确定允许的目标组织，授权、换取令牌及读取身份使用一致上下文 |
| scope 与业务权限 | 仅请求已登记范围；业务菜单、角色及数据范围另行分配 |
| 授权服务器配置 | 确认网关、issuer、授权、令牌、身份查询及退出端点，以目标部署实际结果为准 |
| 退出约定 | 明确只退出当前系统，还是同时注销统一认证会话，以及退出后的合法返回地址 |
回调地址属于接入系统，不能统一填写成登录页，也不要与企微、钉钉的回调混用。终端类型、支持范围和安全要求需按当前部署合同核对。
接入人员：完成授权与回跳
当前已有接入实践采用 OAuth2 授权码＋PKCE、服务端保存令牌和浏览器会话。推荐按以下顺序实现：
- 接入系统创建一次性登录事务，保存 state、PKCE verifier 和允许的站内返回位置。
- 将浏览器引导到授权端点，携带已登记的 client_id、redirect_uri、response_type=code、scope、state 和 S256 code challenge，并传递部署要求的租户上下文。
- 用户在统一认证页登录，必要时确认授权，认证服务将浏览器送回接入系统登记的回调。
- 接入系统校验 state、事务有效期及是否已消费，再由服务端携带授权码、同一回调和 PKCE verifier 换取令牌，按客户端合同完成认证。
- 服务端查询用户信息，核对主体与租户，按业务权限建立本系统会话，返回原先允许的业务页面。
- 无权限、身份不一致或认证服务异常时，明确提示并拒绝受限访问，不因登录成功就开放全部功能。
现有网关接入资料中的接口如下，部署时先核对真实路由，不把登录表单路径当作授权端点。
| 用途 | 以正式网关为例的地址 |
|---|---|
| 发起授权 | https://admin.duoge.work/api/auth/oauth2/authorize |
| 服务端换取令牌 | https://admin.duoge.work/api/auth/oauth2/token |
| 查询当前用户 | https://admin.duoge.work/api/admin/user/info |
| 撤销访问令牌 | https://admin.duoge.work/api/auth/token/logout，按部署合同使用 DELETE |
网关地址与 issuer 可能不同，应按实际元数据和接入合同校验，不能根据域名猜测。客户端 Secret、授权码、令牌及 PKCE verifier 不放入公共文档或浏览器日志；采用上述服务端会话方案时，不把业务令牌发送给前端保存。
统一登录页的协议标识不能单独证明 OIDC 接入已经可用。当前可参照的接入实践是 OAuth2 授权码＋PKCE及用户身份查询；需要 OIDC 的 ID Token、openid scope、发现文档或标准退出时，须先确认目标部署确实提供这些能力。不要仅添加 openid 参数就认定完成 OIDC 集成。
退出与账号权限变化
成员使用当前业务系统的 退出登录 入口，确认已返回退出后的页面。退出当前系统、撤销其访问令牌、注销统一认证会话是不同环节，应由接入方按约定组合实现。
如果只清理当前业务系统会话，下一次登录仍可能复用统一认证会话。需要同时注销统一认证时，应让浏览器按已确认的认证服务退出流程跳转；仅在服务端发送请求不能替代浏览器会话注销。其他系统独立签发的令牌和会话不应直接视为同时退出。
角色调整、停用账号后，应按组织要求检查已有会话、令牌和后续访问结果。授权管理方法见角色与权限分配。
上线前检查与常见问题
| 检查场景 | 应确认的结果 |
|---|---|
| 首次登录 | 选对租户，认证后回到正确业务系统和原目标页面 |
| 已有认证会话 | 按约定复用或重新认证，用户与租户不漂移 |
| 无业务权限账号 | 可以确认身份，但受限内容仍拒绝访问 |
| 取消、错误及过期回调 | 不建立会话，允许用户从正常入口重新发起 |
| 授权码重复使用 | 重复交换被拒绝，不重复建立登录事务 |
| 退出与重新登录 | 当前系统和统一认证会话符合约定，不把页面跳转当成令牌已撤销 |
| 手机及内置浏览器 | 授权跳转、Cookie 与回跳在目标设备单独验证 |
登录页或提交返回 404 时，优先核对认证反向代理是否同时覆盖登录页、表单提交、授权确认、回跳和静态资源，而不只代理 API。回调不匹配时，核对已登记 URL 与实际请求；循环登录时，检查会话 Cookie、HTTPS、代理前缀、state 和租户上下文。登录后无权限时，检查业务角色，不通过扩大 scope 代替业务授权。
本文核对了当前统一登录页、服务端源码及已有本机接入记录；未新建客户端、修改认证配置或完成生产 SSO 联调。正式入口路由及各接入系统仍需上线前逐项验证。