定开 SSO（proinnova-sso）

项目说明与发布（OP）

• 仓库：proinnova-sso

• 产物：proinnova_sso.jar

• 对外路径前缀：/proinnova_sso/（Nginx 反代到 Jar 端口，如 8000）

• 认证策略（SSOStrategyEnum）：当前已实现 CAS、OAUTH2、PASSWORD_FREE，以及基于业务表的 OAUTH2/CAS 等；若现有策略无法满足客户需求，可按枚举扩展新的认证驱动

分支与开发

• 定开 SSO 统一基于 master 分支开发与维护；新客户定开从 master 拉出客户分支（通常以客户编号命名）后按需扩展。

OP 发布要点（详见项目内 README.md）

• Jar：spring.profiles.active 对应 application-{profile}.properties；启动参数 --seepln.account.server=用户中心域名

• 环境变量：ACCOUNT_SERVER 指向用户中心域名

• Nginx：location /proinnova_sso/ { proxy_pass http://ip:port/proinnova_sso/; }

• 用户中心 config.json（非 Jar 内文件）：运维在部署用户中心静态资源时覆盖；OP 定开需配置 environment: "OP" 与 OPLoginConfig

Jar 侧配置（application-*.properties 与 business_table）

proinnova-sso 的认证参数（协议类型、第三方地址、ClientId/Secret、buildAuthUrl 等）写在 Jar 配置或业务模型表中。需与 OPLoginApiUrl、state 及第三方地址等保持一致。

# 基础
xx.base.env=op                       # op | saas
xx.base.domain=xx.com                # 用户中心一级域名（Cookie 域）
xx.base.authStrategy=OAUTH2          # 对应 SSOStrategyEnum：CAS、OAUTH2 等
xx.base.buildAuthUrl=...             # buildAuthUrl?state=xx 最终 302 到的第三方认证地址
xx.base.usernameTurnLowercaseFlag=1

# OAuth2
xx.oauth2.serverUrlPrefix=...
xx.oauth2.authenticationAccessTokenUrl=...
xx.oauth2.authenticationUserinfoUrl=...
xx.oauth2.clientId=...
xx.oauth2.clientSecret=...
xx.oauth2.redirectUri=...            # 与 IdP 登记的回调地址一致，对齐用户中心 `/login` 或 `/login/do-redirect`
xx.base.oauth2UsernameNickname=...   # 从第三方 userinfo JSON 取用户名的字段名

用户中心登录入口与 config.json 配置

config.json 是用户中心前端的运行时配置，不是 proinnova-sso Jar 的 application-*.properties。定开 SSO 场景下，config.json 主要决定两件事：

1. 用户访问 /、/login 时，是直接进入单点登录，还是展示登录页

2. 第三方认证系统回调到用户中心后，前端最终把回调参数转发给哪个后端接口

{
  "environment": "OP",
  "OPLoginConfig": {
    "enabledRedirect": true,
    "pageInnerHTML": "<p style='color:#f00'>自定义HTML</p>",
    "OPLoginApiUrl": "/proinnova_sso/user/getUserInfo?state=xx"
  },
  "loginSetting": {
    "enabledSystemRedirect": true
  }
}

{
  "environment": "OP",
  "OPLoginConfig": {
    "enabledRedirect": false,
    "pageInnerHTML": "<p style='color:#f00'>自定义HTML</p>",
    "OPLoginApiUrl": "/proinnova_sso/user/getUserInfo?state=xx"
  },
  "loginSetting": {
    "enabledSystemRedirect": true
  }
}

第三方 SSO 入口配置

定开 SSO 需要区分两类第三方侧地址，不能混用：

定开登录流程

sequenceDiagram
    participant User as 用户浏览器
    participant IdP as 第三方认证系统
    participant UC as 用户中心 element-login
    participant SSO as proinnova-sso
    participant AC as 账号中心

    User->>SSO: 1. GET /proinnova_sso/user/buildAuthUrl?state=客户编号
    SSO->>IdP: 2. 读取配置并 302 到第三方认证页
    IdP->>UC: 3. 回调 /login 或 /login/do-redirect（携带 ticket/code/state）
    UC->>SSO: 4. 前端中转页 POST OPLoginApiUrl（通常指向 /proinnova_sso/user/getUserInfo）
    SSO->>IdP: 5. 验票 / 换 token / 取用户
    SSO->>AC: 6. POST .../system-login-api/api/oauth/sso/login 或 auth/login
    SSO->>UC: 7. Set-Cookie + 返回 redirect/html
    UC->>User: 8. 跳转产品地址

流程拆解

1. 外部入口发起认证：GET /proinnova_sso/user/buildAuthUrl

• 关键入参：state

• state 两种常见格式：

  • 固定配置模式：{客户编号}

  • 业务模型表模式：{sso_code},business_table

• proinnova-sso 按 state 读取配置后，直接 302 跳转到第三方认证页（buildAuthUrl）

1. IdP 认证后回调用户中心前端

• 回调地址二选一：

  • 仅 SSO（不保留登录页）：{用户中心域名}/login

  • SSO 与登录页并存：{用户中心域名}/login/do-redirect

• 回调参数通常在 query 中，核心为：

  • state（必传）

  • ticket（CAS）或 code（OAuth2）

1. 用户中心前端中转到 proinnova-sso

• 常见中转路由：

  • /login：enabledRedirect=true 时直接进入中转

  • /login/do-redirect：显式中转页（常用于“保留登录页 + SSO 并存”）

• 前端中转页最终复用 redirect.tsx

• 当 environment="OP" 时，前端将回调 query 原样作为 body，POST 到 OPLoginConfig.OPLoginApiUrl（通常是 POST /proinnova_sso/user/getUserInfo）

1. proinnova-sso 验票并调用账号中心登录

驱动选择规则（POST /proinnova_sso/user/getUserInfo）

按所选策略完成验票，并得到第三方用户标识

映射为 DeepFOS 登录用户名并调用账号中心

• OAuth2/CAS 验票成功后得到第三方账号；若配置了 usernameTurnLowercaseFlag，用户名可能转小写

• 最终以映射后的用户名调用账号中心（accountUserInfo = AccountUtils.ssoLogin(...)）：

  • 默认：POST /system-login-api/api/oauth/sso/login（loginParam 为平台用户名）

  • 回调验证场景：POST /system-login-api/api/oauth/sso/auth/login（除 loginParam 外可携带 token、extra_data）

1. 写 Cookie 并完成前端跳转

• 登录成功后由 proinnova-sso 写入主域 Cookie（Driver 的 afterAdvice(...) 中调用 cookieDefend.setCookie(...)）

• 返回 SSOResult（如 redirect / html / manualHandler）

• 用户中心前端根据返回值决定自动跳转或展示错误页（同标准 SSO）

定开开发指引

定开通常围绕 POST /proinnova_sso/user/getUserInfo 开发，其中主要改造点通常是验票 / 换 token / 取用户相关逻辑；账号中心登录、写 Cookie、SSOResult 返回等环节一般可复用现有实现。若需要新增一种认证方式（新 Driver），建议按以下步骤实现：

1. 接入策略并完成分发

• 在 SSOStrategyEnum 增加新的策略类型

• 新增 Driver：实现 AbstractSSODriver（或 AbstractSSOByDBDriver），参考 定开登录流程 与当前已实现的驱动类（如 CASDriverImpl、OAUTH2DriverImpl、PasswordFreeDriverImpl）进行开发

• 在 SSODriverFactory / SSOByDBDriverFactory 注册新 Driver

• 确认 LoginController.getUserInfo 能按 authStrategy（或 business_table）分发到该 Driver

1. 新增 Driver（即 DriverImpl）必做事项（核心）

• 实现验票逻辑（对接第三方认证系统）

• 验票成功后，得到第三方用户标识（如用户名/工号/邮箱）

• 将该标识转换为平台登录入参（通常为 loginParam）

• 调用账号中心登录接口（/system-login-api/api/oauth/sso/login 或 auth/login，即 accountUserInfo = AccountUtils.ssoLogin(...)）

• 登录成功后由 proinnova-sso 写入主域 Cookie（Driver 的 afterAdvice(...) 中调用 cookieDefend.setCookie(...)）

• 最终由统一流程返回 SSOResult（如 redirect / html / manualHandler），供用户中心前端完成最终跳转或错误展示

1. 异常约定

• RedirectException：缺少必填票据（如 code/ticket）或需重新发起认证时抛出；返回中通常带 redirect，前端应跳转回 IdP

• ValidationException：第三方验票失败、账号中心登录失败或关键参数异常时抛出；前端应展示 SSOResult.html（若有）并中止自动跳转

1. 最小联调检查

• 配置一致性：state、回调 URL、authStrategy 与 Driver 注册保持一致

• 验票链路：第三方返回 code/ticket 后，/proinnova_sso/user/getUserInfo 能正确完成验票

• 账号中心登录：验票成功后可调用账号中心并签发登录态（Cookie 正常写入）

• 前端表现：前端可按 SSOResult 正常跳转；异常场景可展示错误页而非静默失败

登录页面改造

当客户要求在 /login 登录页直接展示第三方入口（如企微登录、微软登录等）时，需要改造用户中心前端 element-login，不只依赖后端 SSO 参数。

1. 两类改造方式（实施选择）

• 方式 A：直接改编译后登录页文件（在 /login 对应的前端静态页面 index.html 中，从指定位置贴入自定义代码）

  • 优点：开发轻量，不需要新开前端项目

  • 缺点：运维成本高，需要手工贴代码，发布流程长且容易失败

  • 编译后的 index.html 结构示例（自定义入口代码通常贴在 <body> 内、<div id="root"></div> 前后，以运维/项目约定为准）：

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0"
      />
    <link rel="icon" href="/element-login/favicon.svg" type="image/x-icon" />
    <title>登录</title>
    <script type="module" crossorigin src="/element-login/assets/index-6ba900a9.js"></script>
    <link rel="stylesheet" href="/element-login/assets/index-1e51a7c3.css">
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

• 方式 B：起前端新项目（拉现有资源包，开发完整登录逻辑）

  • 优点：运维更稳定，按服务部署即可，无需上线时手工改文件

  • 缺点：开发成本高，接近完整前端项目改造

1. 前端页面改造点（element-login）

• 在 /login 登录页增加第三方登录入口按钮/区域（文案、图标、点击事件）

• 点击后跳转到定开入口地址，建议使用：

  • /proinnova_sso/user/buildAuthUrl?state=xx

  • 或 /proinnova_sso/user/buildAuthUrl?state={sso_code},business_table

• 在“登录页与 SSO 并存”场景下，可引导到 /login/do-redirect，该地址就是显式中转页