标准 SSO

标准 SSO 控制台配置

标准 SSO 配置统一在企业控制台维护，包括配置入口、支持协议和核心字段。

• 配置入口：企业配置管理 → 企业信息 → 单点登录配置（菜单 code：loginSetting）

• 配置接口前缀：/system-account-api/sso/*

• 登录接口前缀：/system-login-api/api/oauth/sso/*

创建一条标准 SSO 配置时，核心配置项如下：

协议相关配置：

用户中心 config.json 配置

完成控制台配置后，还需确认用户中心前端的 config.json。其中建议重点关注以下两项：

1. environment 需配置为 SAAS 标准 SSO 的固定回调地址为 {用户中心域名}/login/redirect，因此 config.json 中的 environment 需配置为 SAAS，保证 /login/redirect 页面走标准 login-sso 链路；若配置为 OP，则会切换到 OP 定开登录链路。

2. 按需开启 loginSetting.enabledSystemRedirect 若希望标准 SSO 登录成功后，前端按配置项「登录成功后跳转地址（applicationLink）」跳转到指定产品页，则需将 loginSetting.enabledSystemRedirect 设为 true；否则前端会忽略后端返回的 redirect，按默认登录跳转规则处理。

配置示例：

{
  "environment": "SAAS",
  "loginSetting": {
    "enabledSystemRedirect": true
  }
}

统一 SSO 入口配置

标准 SSO 的用户入口应统一配置为平台提供的 /sso/authorize 地址，由平台先按 enterpriseCode + ssoCode 读取启用中的 SSO 配置，再 302 跳转到实际第三方认证页。门户首页、企业微信 / 钉钉应用菜单、浏览器书签等外部入口，都应配置这个平台地址，而不是直接配置第三方 IdP 的 authorize 地址。

统一入口格式：

{用户中心}/system-login-api/api/oauth/sso/authorize?ssoCode={配置编码}&enterpriseCode={企业编码}

参数说明：

企业微信 OAuth2 示例：

• SSO 入口：

GET https://account.deepfos.com/system-login-api/api/oauth/sso/authorize?ssoCode=workWechat&enterpriseCode=default

• 控制台 authorize：

https://open.weixin.qq.com/connect/oauth2/authorize?appid=ww9ff07af05b649ed5&response_type=code&scope=snsapi_base&state=default,workWechat#wechat_redirect

平台实际跳转 IdP 时会自动在末尾追加：&redirect_uri=https://account.deepfos.com/login/redirect。企微应用需在可信域名中允许该回调，且该链接需在 企业微信客户端 内打开。

标准 SSO 登录流程

标准 SSO 统一经平台 /sso/authorize 发起认证，门户、企微/钉钉应用菜单等入口都配置平台链接。

sequenceDiagram
    participant User as 用户浏览器
    participant IdP as 第三方认证系统
    participant UC as 用户中心前端 element-login
    participant AC as 账号中心 seepln-account
    participant App as DeepFOS 产品

    User->>AC: 1. GET .../sso/authorize?ssoCode&enterpriseCode
    AC->>IdP: 2. 读配置并 302 到 IdP
    IdP->>UC: 3. 回调 /login/redirect?code/ticket&state
    Note over UC: sso-redirect.tsx<br/>POST .../login-sso
    UC->>AC: 4. 回调参数原样透传给 login-sso
    AC->>IdP: 5. 验票 / 换 Token / 拉用户信息
    AC->>AC: 6. 映射平台用户、生成 Token、写 Cookie
    AC-->>UC: 7. 返回跳转参数
    UC->>App: 8. 进入产品

流程拆解

1. 平台发起认证：GET /system-login-api/api/oauth/sso/authorize

   入参

   • enterpriseCode

   • ssoCode

   后端处理

   • 按 enterpriseCode + ssoCode + status=true 查询启用中的 SSO 配置

   • 根据 ssoType 生成第三方认证地址

   • OAuth2：读取控制台 authorize，追加 &redirect_uri={用户中心域名}/login/redirect

   • CAS：拼 {casApi}/login?service={用户中心域名}/login/redirect

   返回

   • 不返回 JSON，直接 302 redirect 到第三方认证页

   • 到达第三方认证页后，IdP 会先识别当前用户：若已存在有效登录态，通常可直接完成认证并回调平台，带回 code 或 ticket 等认证结果；若尚未登录，则需先在 IdP 完成登录后再继续

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

   回调地址

   • 固定为 {用户中心域名}/login/redirect

   常见回调参数

   • OAuth2 / MS_AAD：code、state

   • CAS：ticket、state

   说明

   • state 格式固定为 {enterpriseCode},{ssoCode}

   • 平台不会自动生成 state，需提前写在 OAuth2 的 authorize 中

3. 前端中转：将回调 query 原样 POST 给 login-sso

   前端路由

   • /login/redirect → sso-redirect.tsx

   前端行为

   • 读取地址栏 query 参数

   • 将整包 query 作为 JSON body 提交到 POST /system-login-api/api/oauth/sso/login-sso

   因此 login-sso 通常至少会收到

   • state

   • code 或 ticket

4. 核心验票：POST /system-login-api/api/oauth/sso/login-sso

   login-sso 是标准 SSO 的核心接口，既负责第三方验票，也负责生成平台登录态。

   第一步：按 state 选中正确的 SSO 配置

   • 校验 state 是否存在且包含逗号

   • 拆出 enterpriseCode、ssoCode

   • 查询当前启用的配置，拿到：ssoType、enterpriseId、userKey、customKey、applicationLink、协议明细配置

   第二步：按协议处理第三方身份

   OAuth2

   • 从回调参数中取授权码：默认读取 code；若配置了 ticketKeyName，则按该键名读取

   • 调 tokenApi 换 Token，请求通常包含：clientIdKeyName=clientId、clientSecretKeyName=clientSecret、grant_type=tokenGrantType、oauth_timestamp=当前时间戳、code=授权码、redirect_uri={用户中心域名}/login/redirect

   • 从响应 JSON 中读取 access_token

   • 再调 userInfoApi?access_token=...&code=... 拉取用户信息

   • 若配置 userIdFlag=1，则先取 userIdName，再调用 userIdApi 查详情

   • 最终按 customKey 提取第三方用户标识：若配置了 userInfoApiSearchPath 则按 JSONPath 读取，否则直接从 JSON 顶层取值

   MS_AAD

   • 整体流程与 OAuth2 相同

   • Token 请求和 UserInfo 请求按微软接口规范处理，例如通过 Authorization: Bearer {accessToken} 访问用户信息接口

   CAS

   • 从回调参数中取 ticket

   • 调 {casApi}/serviceValidate?ticket=...&format=xml&service={用户中心域名}/login/redirect

   • 解析 CAS 返回 XML，按 customKey 提取第三方用户标识

   协议处理完成后，统一得到

   • value：第三方用户标识

   • userKey：该标识要映射到 DeepFOS 的哪个账户字段

5. 用户映射、写 Cookie、返回跳转结果

   平台查找用户

   • 调用 findUserBySso(value, userKey, enterpriseId, ssoCode, false)，查找当前企业、当前 SSO 配置下对应的 DeepFOS 用户

   若找不到用户

   • 返回「用户不存在」等异常

   • 说明第三方身份尚未与平台账号建立映射

   若找到用户

   • 调 tokenOperationManage.generateToken(...) 生成平台登录态

   • 调 cookieDefend.setCookie(...) 写入主域 Cookie

   • 返回 SSOResultDTO

   SSOResultDTO 在不同场景下的主要返回内容如下：

   字段	成功场景	异常场景（后端捕获 SSOException）
   redirect	默认取当前配置的 applicationLink	通常不作为前端跳转依据
   登录用户信息	如 token、username、email 等	通常为空或不作为主要处理内容
   html	通常为空	为后端异常处理返回的错误页 HTML
   manualHandler	通常为 false	固定为 true

6. 前端收到 SSOResultDTO 后的处理流程

   前端收到 SSOResultDTO 后，按以下规则决定是否展示错误页或继续跳转：

flowchart LR
    A[收到 SSOResultDTO] --> B{manualHandler=true?}
    B -- 是 --> C[展示 html, 不自动跳转]
    B -- 否 --> D{enabledSystemRedirect=true?}
    D -- 是 --> E{是否返回 redirect?}
    E -- 是 --> F[跳转到 redirect]
    E -- 否 --> G[按默认登录跳转规则处理]
    D -- 否 --> G
    G --> H{loginDefaultRedirect='lastApp'?}
    H -- 是 --> I{能否获取最近访问应用?}
    I -- 是 --> J[跳转最近访问应用]
    I -- 否 --> K[跳转 accountWebAddress]
    H -- 否 --> K
    K --> L{accountWebAddress 是否已配置?}
    L -- 是 --> M[跳转账户中心前端默认首页]
    L -- 否 --> N[兜底跳转到 /]

其中 loginSetting.enabledSystemRedirect、loginSetting.loginDefaultRedirect 与 account.accountWebAddress 均为用户中心前端 config.json 中的配置项；redirect 通常取当前配置的 applicationLink。